@octane-xplat/ui 0.5.0 → 0.7.0

package/src/Table.tsrx

@@ -0,0 +1,37 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { TableProps, TableColumn } from "./props";
+import { cx } from "./cx";
+import { applyEscapeProps } from "./escape-props";
+
+/** Table — self-drawn grid. Bounded and unvirtualized: large datasets
+ *  belong to the platform UITableView/RecyclerView subpaths. */
+export function Table(props: TableProps) @{
+	const cellStyle = (col: TableColumn) => ({
+		...(col.width != null ? { width: col.width } : { flexGrow: 1 }),
+		...(col.align ? { textAlignment: col.align } : {}),
+	});
+
+	<flexboxlayout ref={(v: any) => applyEscapeProps(v, props)} id={props.id} className={cx('vx-table', props.className)} style={props.style}>
+		<flexboxlayout className="vx-table-head">
+			@for (const col of props.columns; key col.key) {
+				<flexboxlayout className="vx-table-cell vx-table-th" style={cellStyle(col)}>
+					<label text={col.label ?? col.key} />
+				</flexboxlayout>
+			}
+		</flexboxlayout>
+		{props.rows.length === 0 && props.empty != null
+			? <flexboxlayout className="vx-table-empty">{props.empty}</flexboxlayout>
+			: @for (const e of props.rows.map((row, ri) => ({ row, ri })); key props.keyFor ? props.keyFor(e.row, e.ri) : String(e.ri)) {
+				<flexboxlayout
+					className={cx('vx-table-row', props.onRowPress && 'vx-table-row--pressable')}
+					onTap={props.onRowPress ? () => props.onRowPress!(e.row, e.ri) : undefined}
+				>
+					@for (const col of props.columns; key col.key) {
+						<flexboxlayout className="vx-table-cell" style={cellStyle(col)}>
+							{props.renderCell ? props.renderCell(e.row, col, e.ri) : <label text={String(e.row[col.key] ?? '')} />}
+						</flexboxlayout>
+					}
+				</flexboxlayout>
+			}}
+	</flexboxlayout>
+}

package/src/Table.web.tsrx

@@ -0,0 +1,37 @@
+import type { TableProps, TableColumn } from "./props";
+import { applyEscapeProps } from "./escape-props";
+
+/** Table — self-drawn grid. Bounded and unvirtualized: large datasets
+ *  belong to the platform UITableView/RecyclerView subpaths. */
+export function Table(props: TableProps) @{
+	const cellStyle = (col: TableColumn) => ({
+		...(col.width != null ? { width: col.width } : { flex: 1 }),
+		...(col.align ? { textAlign: col.align } : {}),
+	});
+
+	<div ref={(e: any) => applyEscapeProps(e, props)} id={props.id} className={['vx-table', props.className]} style={props.style} role="table">
+		<div className="vx-table-head" role="row">
+			{props.columns.map((col: TableColumn) => (
+				<div key={col.key} className="vx-table-cell vx-table-th" role="columnheader" style={cellStyle(col)}>
+					{col.label ?? col.key}
+				</div>
+			))}
+		</div>
+		{props.rows.length === 0 && props.empty != null
+			? <div className="vx-table-empty">{props.empty}</div>
+			: props.rows.map((row: Record<string, any>, ri: number) => (
+				<div
+					key={props.keyFor ? props.keyFor(row, ri) : ri}
+					className={['vx-table-row', props.onRowPress ? 'vx-table-row--pressable' : undefined]}
+					role="row"
+					onClick={props.onRowPress ? () => props.onRowPress!(row, ri) : undefined}
+				>
+					{props.columns.map((col: TableColumn) => (
+						<div key={col.key} className="vx-table-cell" role="cell" style={cellStyle(col)}>
+							{props.renderCell ? props.renderCell(row, col, ri) : String(row[col.key] ?? '')}
+						</div>
+					))}
+				</div>
+			))}
+	</div>
+}

package/src/Tabs.macos.tsrx

@@ -0,0 +1,60 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import { createContext, useContext, useState } from 'octane'
+import type { TabsProps } from './props'
+import { cx } from './cx'
+import { Pressable } from './Pressable.macos.tsrx'
+import { Text } from './Text.macos.tsrx'
+import { RouteHost } from './RouteHost.macos.tsrx'
+import { layoutsFor, useRoute, screenFor } from './route.macos'
+
+function screenParams(route: NonNullable<ReturnType<typeof useRoute>>) {
+	const params: Record<string, unknown> = { ...route.params, ...(route.context ?? {}), _stack: route.stack, _pushed: true }
+	if (Object.prototype.hasOwnProperty.call(route, 'loaderData')) {params.data = route.loaderData}
+	if (Object.prototype.hasOwnProperty.call(route, 'loaderError')) {params.error = route.loaderError}
+	return params
+}
+
+// Stacks already presented by an ancestor Tabs. The AppKit host has no root
+// Frame, so a stackless tab pane presents the 'root' stack's top route — but
+// a Tabs nested inside a presented screen (e.g. a fixture mounted by that
+// very route) must not re-present the same stack, which would recurse until
+// the JS stack overflows.
+const PresentedStacks: any = createContext(null)
+
+export function Tabs(props: TabsProps) @{
+	const [internal, setInternal] = useState(0)
+	const presented: Set<string> = useContext(PresentedStacks) ?? new Set()
+	const active = props.selectedIndex ?? internal
+	const tab = props.tabs[active]
+	const route = useRoute(tab?.stack ?? 'root')
+	const presentable = route && !presented.has(route.stack) ? route : null
+	const Screen = presentable ? screenFor(presentable.name) : undefined
+
+	<flexboxlayout
+		id={props.id}
+		flexDirection="column"
+		className={cx('vx-tabs', props.className)}
+		style={props.style}
+	>
+		<flexboxlayout flexDirection="row" className="vx-tabbar">
+			@for (const item of props.tabs; index i; key item.title) {
+				<Pressable
+					id={'tab-' + i}
+					className={cx('vx-tab', active === i ? 'active' : '')}
+					onPress={() => { setInternal(i); props.onSelectedIndexChanged?.(i); }}
+				>
+					<Text>{item.title}</Text>
+				</Pressable>
+			}
+		</flexboxlayout>
+		<flexboxlayout flexDirection="column" className="vx-tabpane flex-1">
+			@if (presentable && Screen) {
+				<PresentedStacks value={new Set(presented).add(presentable.stack)}>
+					<RouteHost screen={Screen} layouts={layoutsFor(presentable.name)} params={screenParams(presentable)} />
+				</PresentedStacks>
+			} @else {
+				<>{tab?.render()}</>
+			}
+		</flexboxlayout>
+	</flexboxlayout>
+}

package/src/Tabs.tsrx

@@ -0,0 +1,55 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useState } from 'octane';
+import { cx } from './cx';
+import { Icon } from './Icon.tsrx';
+import { Pressable } from './Pressable.tsrx';
+import { Text } from './Text.tsrx';
+import { layoutsForRoute, screenFor, useRoute } from './route';
+import { RouteHost, screenParamsFor } from './route-host.mobile';
+import type { TabSpec, TabsProps } from './props';
+
+export type { TabSpec } from './props';
+
+/** Self-drawn tab shell — a fixed Pressable row plus a single swapped pane,
+ *  identical on every target (the same shape as the web leaf). Route
+ *  history for `stack` panes lives in the route store, so switching tabs
+ *  keeps each stack's entries; pushed screens render through RouteHost.
+ *  The platform tab bar (UITabBar/BottomNavigationView — real UITabBarItem
+ *  chrome, per-pane Frames) lives in `ui/ios` + `ui/android`.
+ *  `tabs` is identity-stable (module const preferred). */
+export function Tabs(props: TabsProps) @{
+	const [internal, setInternal] = useState(0);
+	const active = props.selectedIndex ?? internal;
+	const tab = props.tabs[active];
+	const route = useRoute(tab?.stack ?? '');
+	const Screen = route ? screenFor(route.name) : undefined;
+	const columns = props.tabs.map(() => '*').join(',');
+
+	<gridlayout rows="auto,*" id={props.id} className={cx(props.className)} style={props.style}>
+		<gridlayout row={0} columns={columns} className="vx-tabbar">
+			@for (const t of props.tabs; index i; key t.title) {
+				<Pressable
+					col={i}
+					className={cx('vx-tab', active === i ? 'active' : '')}
+					onPress={() => { setInternal(i); props.onSelectedIndexChanged?.(i); }}
+				>
+					@if (t.icon) {
+						<Icon name={t.icon} className="vx-tabicon" size={18} />
+					}
+					<Text>{t.title}</Text>
+				</Pressable>
+			}
+		</gridlayout>
+		<gridlayout row={1} className={cx('vx-tabpane', route?.presentation === 'fade' ? 'vx-route--fade' : '')}>
+			@if (route && Screen) {
+				<RouteHost
+					screen={Screen}
+					layouts={layoutsForRoute(route.name)}
+					params={screenParamsFor(route)}
+				/>
+			} @else {
+				<>{tab?.render()}</>
+			}
+		</gridlayout>
+	</gridlayout>
+}

package/src/Tabs.web.tsrx

@@ -0,0 +1,98 @@
+import { createContext, useContext, useState } from 'octane';
+import type { TabSpec, TabsProps } from './props';
+import { Icon } from './Icon.web.tsrx';
+
+import { canGoBack, layoutsFor, popRoute, screenFor, useModalRoute, useRoute } from './route.web';
+
+export type { TabSpec } from './props';
+
+// Stacks already presented by an ancestor Tabs — a nested Tabs inside a
+// routed screen must not re-present the same stack, or the screen's subtree
+// would recursively contain the route again (e.g. a stackless fixture inside
+// a pushed screen that re-presents 'root').
+const PresentedStacks: any = createContext(null);
+
+/** Platform tab shell — web version: a button row + the active pane. The
+ *  pane also acts as the route outlet for its `stack`; a route on the
+ *  'root' stack covers the whole shell (native: root push covers tabs). */
+export function Tabs(props: TabsProps) @{
+	const [internal, setInternal] = useState(0);
+	const active = props.selectedIndex ?? internal;
+	const presented: Set<string> = useContext(PresentedStacks) ?? new Set();
+	const rootRoute = useRoute('root');
+	// Hooks must be unconditional — subscribe with the active pane's stack
+	// name ('' never matches a route).
+	const paneRoute = useRoute(props.tabs[active]?.stack ?? '');
+	const modal = useModalRoute();
+	// resolveScreen prop wins; the registerScreens table is the fallback —
+	// one registration serves both platforms' outlets. Directory _layout
+	// files wrap the resolved element either way (outermost → innermost).
+	const resolve = (name: string, params: Record<string, unknown>) => {
+		const C = screenFor(name);
+		const el = props.resolveScreen
+			? props.resolveScreen(name, params)
+			: C
+				? <C {...params} />
+				: null;
+
+		return layoutsFor(name).reduceRight((child, L) => <L>{child}</L>, el);
+	};
+
+	const routeProps = (route: NonNullable<typeof rootRoute> | NonNullable<typeof paneRoute>) => ({
+		...route.params,
+		...(route.context ?? {}),
+		_pushed: canGoBack(route.stack),
+		...(Object.prototype.hasOwnProperty.call(route, 'loaderData') ? { data: route.loaderData } : {}),
+		...(Object.prototype.hasOwnProperty.call(route, 'loaderError') ? { error: route.loaderError } : {}),
+	});
+
+	const presentedWith = (stack: string) => new Set(presented).add(stack);
+	const routed = rootRoute && !presented.has('root')
+		? resolve(rootRoute.name, routeProps(rootRoute))
+		: null;
+
+	// A modal route overlays the shell without replacing it — the screen
+	// gets a `close` prop (popRoute parity with the native showModal root).
+	const modalContent = modal && !presented.has(modal.stack)
+		? resolve(modal.name, { ...routeProps(modal), close: () => popRoute() })
+		: null;
+
+	<div className="vx-tabsroot" style={{ display: 'contents' }}>
+	@if (routed) {
+		<PresentedStacks value={presentedWith('root')}>
+			<div className="vx-route">{routed}</div>
+		</PresentedStacks>
+	}
+	@else {
+	<div id={props.id} className={['vx-tabs', props.className]} style={{ ...(props.style?.height != null ? { flex: 'none' } : {}), ...props.style }}>
+		<div className="vx-tabbar">
+			@for (const t of props.tabs; key t.title) {
+				<button
+					className={['vx-tab', active === props.tabs.indexOf(t) ? 'active' : '']}
+					onClick={() => {
+						const i = props.tabs.indexOf(t);
+						setInternal(i);
+						props.onSelectedIndexChanged?.(i);
+					}}
+				>
+					{t.icon ? <Icon name={t.icon} className="vx-tabicon" size={16} /> : null}
+					{t.title}
+				</button>
+			}
+		</div>
+		<div className="vx-tabpane">
+			{(paneRoute && !presented.has(paneRoute.stack)
+				? <PresentedStacks value={presentedWith(paneRoute.stack)}>{resolve(paneRoute.name, routeProps(paneRoute))}</PresentedStacks>
+				: null)
+				?? props.tabs[active]?.render()}
+		</div>
+	</div>
+	}
+	@if (modalContent) {
+		<div className="vx-modalroute">
+			<button className="vx-modalroute-shade" aria-label="Dismiss" onClick={() => popRoute()} />
+			<div className="vx-modalroute-body"><PresentedStacks value={presentedWith(modal?.stack ?? '')}>{modalContent}</PresentedStacks></div>
+		</div>
+	}
+	</div>
+}

package/src/Text.macos.tsrx

@@ -0,0 +1,18 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { RichTextProps, RichTextSpanProps, TextProps } from './props'
+
+export function Text(props: TextProps) @{
+	<label id={props.id} className={props.className} style={props.style} accessibilityLabel={props.accessibilityLabel} accessibilityRole={props.accessibilityRole}>
+		{props.children}
+	</label>
+}
+
+export function RichText(props: RichTextProps) @{
+	<label id={props.id} className={props.className} style={props.style} accessibilityLabel={props.accessibilityLabel}>
+		{props.children}
+	</label>
+}
+
+export function RichTextSpan(props: RichTextSpanProps) @{
+	<span className={props.className} style={props.style}>{props.children}</span>
+}

package/src/Text.tsrx

@@ -0,0 +1,62 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { createContext, useContext } from 'octane';
+import type { TextProps } from "./props";
+import { cx } from "./cx";
+import { applyEscapeProps, nativeAccessibilityRole, nativeAccessibilityState } from "./escape-props";
+import { layoutChildProps } from './layout-child';
+
+/**
+ * Nested <Text> renders a <span> (rich-text run) inside the parent's
+ * label/formattedstring. Note: span-under-TextBase parenting needs the
+ * driver extension from docs/decisions.md #25 — bare-text-only usage is
+ * safe today.
+ */
+// The 'octane' import is compiler-retargeted to the universal runtime on
+// native; its DOM Context type signature (2-3 args) doesn't match the
+// universal 1-arg callable, so type the value loosely for this leaf.
+const InText: any = createContext(false);
+
+/** Function-component wrapper: context callables aren't JSX.ElementType under
+ *  the nativescript intrinsics, so provide through a component shape. */
+function TextScope(props: { children?: any }) {
+	return InText({ value: true, children: props.children });
+}
+
+export function Text(props: TextProps) @{
+	const inText = useContext(InText);
+	const textStyle = {
+		...props.style,
+		// Clamped text must be allowed to shrink — the shared shrink:0 default
+		// would let the label overflow its row instead of truncating.
+		...(props.ellipsize || props.numberOfLines ? { flexShrink: 1 } : {}),
+		...(props.ellipsize ? { whiteSpace: 'nowrap', textOverflow: 'ellipsis' } : {}),
+	};
+
+	@if (inText) {
+		<span ref={(v: any) => applyEscapeProps(v, props)} className={cx(props.className)} style={textStyle} {...layoutChildProps(props)}>
+			{props.children}
+		</span>
+	} @else {
+		<label
+			id={props.id}
+			ref={(v: any) => applyEscapeProps(v, props)}
+			{...layoutChildProps(props)}
+			className={cx(props.className)}
+			style={textStyle}
+			maxLines={props.numberOfLines ?? 0}
+			// NS Label renders single-line unless whiteSpace asks to wrap;
+			// web text wraps freely — 'normal' matches web (0 = unlimited lines).
+			whiteSpace={props.ellipsize ? 'nowrap' : 'normal'}
+			textOverflow={props.ellipsize ? 'ellipsis' : undefined}
+			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}
+		>
+			<TextScope>{props.children}</TextScope>
+		</label>
+	}
+}

package/src/Text.web.tsrx

@@ -0,0 +1,31 @@
+import type { TextProps } from "./props";
+import { applyEscapeProps } from "./escape-props";
+import { layoutChildProps } from './layout-child.web';
+export function Text(props: TextProps) @{
+	const textStyle = {
+		...props.style,
+		...(props.numberOfLines ? { display: '-webkit-box', WebkitLineClamp: props.numberOfLines, WebkitBoxOrient: 'vertical', overflow: 'hidden' } : {}),
+		// Clamped text must be allowed to shrink — the shared shrink:0 default
+		// would let it overflow its row instead of truncating.
+		...(props.ellipsize || props.numberOfLines ? { flexShrink: 1 } : {}),
+		...(props.ellipsize ? { textOverflow: 'ellipsis', whiteSpace: 'nowrap', overflow: 'hidden' } : {}),
+	};
+
+	<span
+		id={props.id}
+		ref={(el: any) => applyEscapeProps(el, props)}
+		className={props.className}
+		{...layoutChildProps(props, textStyle)}
+		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}
+	</span>
+}

package/src/TextArea.tsrx

@@ -0,0 +1,65 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useEffect, useRef } from 'octane';
+import { Utils } from '@nativescript/core';
+import type { TextAreaProps } from "./props";
+import { cx } from "./cx";
+import { applyEscapeProps } from "./escape-props";
+import { writeText } from './text-write';
+
+/** Multiline input — <textview>. TextView measures to content natively, so
+ *  `autoGrow` is its default; `rows`/`maxRows` have no NS equivalent, so the
+ *  leaf converts them to min/maxHeight in dips using the widget's own line
+ *  height (iOS `font.lineHeight`, Android `getLineHeight()` px→dip — measured
+ *  on `loaded`, re-fit every commit for prop/style changes). The driver's
+ *  text→textChange echo suppression applies here unchanged. */
+export function TextArea(props: TextAreaProps) @{
+	const el = useRef<any>(null);
+	const submitOnReturn = props.returnKeyType === 'done' || props.returnKeyType === 'send';
+
+	const lineDip = (v: any): number => {
+		const ios = v?.ios?.font?.lineHeight;
+		if (ios > 0) return ios;
+		const px = v?.android?.getLineHeight?.();
+		if (px > 0) return Utils.layout.toDeviceIndependentPixels(px);
+		return 24; // ≈ default 17pt at 1.4 — only hit before widget load
+	};
+
+	const fit = (v: any) => {
+		if (!v) return;
+		if (props.style?.height != null) return; // explicit height wins
+		const line = lineDip(v);
+		const rows = props.rows ?? (props.autoGrow ? 1 : 3);
+		v.style.minHeight = rows * line;
+		if (props.maxRows) v.style.maxHeight = props.maxRows * line;
+		else if (!props.autoGrow) v.style.maxHeight = rows * line;
+	};
+
+	// Explicit deps — tsrx infers effect deps from closure reads, and `fit`
+	//  hides the prop reads one level down.
+	useEffect(() => fit(el.current), [props.rows, props.autoGrow, props.maxRows, props.style]);
+	// Imperative controlled write — Android setText resets selection to 0.
+	useEffect(() => writeText(el.current, props.value), [props.value]);
+
+	<textview
+		id={props.id}
+		ref={(v: any) => {
+			el.current = v;
+			if (!v) return;
+			applyEscapeProps(v, props);
+			props.bind?.({ focus: () => v.focus(), blur: () => v.dismissSoftInput?.() ?? v.blur(), native: v });
+		}}
+		className={cx('vx-textarea', props.className)}
+		style={{ ...props.style, ...(props.placeholderTextColor ? { placeholderColor: props.placeholderTextColor } : {}) }}
+		hint={props.placeholder}
+		keyboardType={props.keyboardType === 'default' ? undefined : props.keyboardType}
+		returnKeyType={props.returnKeyType}
+		editable={props.editable ?? true}
+		onLoaded={(e: any) => fit(e.object)}
+		onTextChange={(e: any) => props.onChange?.(e.value)}
+		// TextView emits returnPress for every newline. Only an explicit action
+		// key opts into the submit semantic; ordinary Return remains a newline.
+		onReturnPress={submitOnReturn ? props.onSubmit : undefined}
+		onFocus={props.onFocus}
+		onBlur={props.onBlur}
+	/>
+}

package/src/TextArea.web.tsrx

@@ -0,0 +1,61 @@
+import { useLayoutEffect, useRef } from 'octane';
+import { normStyle } from './layout-child.web';
+import type { TextAreaProps } from "./props";
+import { applyEscapeProps } from "./escape-props";
+
+/** Multiline input — <textarea>. `autoGrow` re-fits height to content after
+ *  every commit via scrollHeight, capped by `maxRows` translated to a real
+ *  max-height from the element's computed line-height; past the cap the
+ *  field scrolls. `useLayoutEffect` so the measure lands pre-paint in the
+ *  commit that wrote `value`. Deps are explicit — tsrx infers them from the
+ *  closure's reads otherwise, and `props.value` (the thing that changes the
+ *  height) isn't read inside. */
+export function TextArea(props: TextAreaProps) @{
+	const el = useRef<HTMLTextAreaElement | null>(null);
+
+	useLayoutEffect(() => {
+		const t = el.current;
+		if (!t) return;
+		const cs = getComputedStyle(t);
+		const pad = parseFloat(cs.paddingTop) + parseFloat(cs.paddingBottom);
+		const bord = parseFloat(cs.borderTopWidth) + parseFloat(cs.borderBottomWidth);
+		// scrollHeight is always content+padding; CSS height counts padding
+		// +border only under border-box — convert between the two metrics.
+		const adj = cs.boxSizing === 'border-box' ? bord : -pad;
+		const line = parseFloat(cs.lineHeight) || parseFloat(cs.fontSize) * 1.2;
+		const cap = props.maxRows
+			? props.maxRows * line + (cs.boxSizing === 'border-box' ? pad + bord : 0)
+			: parseFloat(cs.maxHeight) || Infinity;
+
+		if (props.maxRows) t.style.maxHeight = Math.ceil(cap) + 'px';
+		if (props.autoGrow) {
+			t.style.height = 'auto';
+			// scrollHeight ≥ clientHeight at auto — the rows attr is the floor.
+			const need = t.scrollHeight + adj;
+			t.style.height = Math.min(need, cap) + 'px';
+			t.style.overflowY = need > cap ? 'auto' : 'hidden';
+		}
+	}, [props.value, props.rows, props.autoGrow, props.maxRows, props.className, props.style]);
+
+	<textarea
+		ref={(node: any) => {
+			el.current = node;
+			if (!node) return;
+			applyEscapeProps(node, props);
+			props.bind?.({ focus: () => node.focus(), blur: () => node.blur(), native: node });
+		}}
+		id={props.id}
+		className={['vx-textarea', props.className]}
+		style={{ ...normStyle(props.style), ...(props.placeholderTextColor ? { '--placeholder-color': props.placeholderTextColor } : {}) }}
+		value={props.value}
+		inputMode={props.keyboardType === 'number' ? 'numeric' : props.keyboardType === 'phone' ? 'tel' : props.keyboardType === 'default' ? 'text' : props.keyboardType}
+		enterKeyHint={props.returnKeyType}
+		readOnly={props.editable === false}
+		placeholder={props.placeholder}
+		rows={props.rows ?? (props.autoGrow ? 1 : 3)}
+		onInput={(e: any) => props.onChange?.(e.target.value)}
+		onKeyDown={(e: any) => { if (e.key === 'Enter' && (e.ctrlKey || e.metaKey)) props.onSubmit?.(); }}
+		onFocus={props.onFocus}
+		onBlur={props.onBlur}
+	/>
+}

package/src/TextInput.tsrx

@@ -0,0 +1,39 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useEffect, useRef } from 'octane';
+import type { TextInputProps } from "./props";
+import { cx } from "./cx";
+import { applyEscapeProps } from "./escape-props";
+import { writeText } from './text-write';
+
+/** Controlled single-line input. The driver suppresses the textChange echo
+ *  of its own `text` writes (upstream #5, since 0.2.1) — no leaf-side
+ *  guard needed. `editable` defaults true at the leaf too: an undefined
+ *  write coerces ios.userInteractionEnabled to NO (dead field) — the
+ *  driver's skip-undefined patch covers it, the ?? stays as documentation.
+ *  `text` isn't a bound prop: the leaf writes it imperatively so the
+ *  Android selection survives controlled writes (see text-write). */
+export function TextInput(props: TextInputProps) @{
+	const el = useRef<any>(null);
+	useEffect(() => writeText(el.current, props.value), [props.value]);
+
+	<textfield
+		ref={(v: any) => {
+			el.current = v;
+			if (!v) return;
+			applyEscapeProps(v, props);
+			props.bind?.({ focus: () => v.focus(), blur: () => v.dismissSoftInput?.() ?? v.blur(), native: v });
+		}}
+		id={props.id}
+		className={cx('vx-input', props.className)}
+		style={{ ...props.style, ...(props.placeholderTextColor ? { placeholderColor: props.placeholderTextColor } : {}) }}
+		hint={props.placeholder}
+		secure={props.secure}
+		keyboardType={props.keyboardType === 'default' ? undefined : props.keyboardType}
+		returnKeyType={props.returnKeyType}
+		editable={props.editable ?? true}
+		onTextChange={(e: any) => props.onChange?.(e.value)}
+		onReturnPress={props.onSubmit}
+		onFocus={props.onFocus}
+		onBlur={props.onBlur}
+	/>
+}

package/src/TextInput.web.tsrx

@@ -0,0 +1,28 @@
+import { normStyle } from './layout-child.web';
+import type { TextInputProps } from "./props";
+import { applyEscapeProps } from "./escape-props";
+export function TextInput(props: TextInputProps) @{
+	const keyboardType = props.keyboardType === 'phone' ? 'tel' : props.keyboardType === 'default' ? 'text' : props.keyboardType;
+	const inputMode = props.keyboardType === 'number' ? 'numeric' : props.keyboardType === 'phone' ? 'tel' : props.keyboardType === 'default' ? 'text' : props.keyboardType;
+
+	<input
+		ref={(el: any) => {
+			if (!el) return;
+			applyEscapeProps(el, props);
+			props.bind?.({ focus: () => el.focus(), blur: () => el.blur(), native: el });
+		}}
+		id={props.id}
+		className={['vx-input', props.className]}
+		style={{ ...normStyle(props.style), ...(props.placeholderTextColor ? { '--placeholder-color': props.placeholderTextColor } : {}) }}
+		value={props.value}
+		type={props.secure ? 'password' : props.keyboardType === 'number' || props.keyboardType === 'decimal' ? 'number' : keyboardType}
+		inputMode={inputMode}
+		enterKeyHint={props.returnKeyType}
+		readOnly={props.editable === false}
+		placeholder={props.placeholder}
+		onInput={(e: any) => props.onChange?.(e.target.value)}
+		onKeyDown={(e: any) => { if (e.key === 'Enter' && !e.shiftKey) props.onSubmit?.(); }}
+		onFocus={props.onFocus}
+		onBlur={props.onBlur}
+	/>
+}

package/src/Timeline.macos.tsrx

@@ -0,0 +1,27 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { TimelineProps } from "./props";
+import { cx } from "./cx";
+import { applyEscapeProps } from "./escape-props";
+import { Icon } from './Icon.macos.tsrx';
+
+/** Timeline — vertical event list: dot + connector + content per item. */
+export function Timeline(props: TimelineProps) @{
+	<flexboxlayout ref={(v: any) => applyEscapeProps(v, props)} id={props.id} className={cx('vx-timeline', props.className)} style={props.style}>
+		@for (const e of props.items.map((item, i) => ({ item, i })); key e.item.key) {
+			<flexboxlayout className="vx-timeline-item">
+				{/* rail/dot/line metrics are CSS on web — inline equivalents
+				   here (AppKit has no style layer); keep in step with
+				   .vx-timeline-* */}
+				<flexboxlayout className="vx-timeline-rail" style={{ width: 20 }} alignItems="center">
+					<flexboxlayout className="vx-timeline-dot" style={{ width: 10, height: 10, borderRadius: 5, backgroundColor: '#171717' }}>{e.item.icon ? <Icon name={e.item.icon} /> : null}</flexboxlayout>
+					{e.i < props.items.length - 1 ? <flexboxlayout className="vx-timeline-line flex-1" style={{ width: 1, backgroundColor: '#d4d4d4' }} /> : null}
+				</flexboxlayout>
+				<flexboxlayout className="vx-timeline-body">
+					{e.item.time != null ? <label className="vx-timeline-time" text={e.item.time} /> : null}
+					{e.item.title != null ? <label className="vx-timeline-title" text={e.item.title} /> : null}
+					{e.item.description != null ? <label className="vx-timeline-desc" text={e.item.description} /> : null}
+				</flexboxlayout>
+			</flexboxlayout>
+		}
+	</flexboxlayout>
+}

package/src/Timeline.tsrx

@@ -0,0 +1,24 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { TimelineProps } from "./props";
+import { cx } from "./cx";
+import { applyEscapeProps } from "./escape-props";
+import { Icon } from './Icon.tsrx';
+
+/** Timeline — vertical event list: dot + connector + content per item. */
+export function Timeline(props: TimelineProps) @{
+	<flexboxlayout ref={(v: any) => applyEscapeProps(v, props)} id={props.id} className={cx('vx-timeline', props.className)} style={props.style}>
+		@for (const e of props.items.map((item, i) => ({ item, i })); key e.item.key) {
+			<flexboxlayout className="vx-timeline-item">
+				<flexboxlayout className="vx-timeline-rail">
+					<flexboxlayout className="vx-timeline-dot">{e.item.icon ? <Icon name={e.item.icon} /> : null}</flexboxlayout>
+					{e.i < props.items.length - 1 ? <flexboxlayout className="vx-timeline-line" /> : null}
+				</flexboxlayout>
+				<flexboxlayout className="vx-timeline-body">
+					{e.item.time != null ? <label className="vx-timeline-time" text={e.item.time} /> : null}
+					{e.item.title != null ? <label className="vx-timeline-title" text={e.item.title} /> : null}
+					{e.item.description != null ? <label className="vx-timeline-desc" text={e.item.description} /> : null}
+				</flexboxlayout>
+			</flexboxlayout>
+		}
+	</flexboxlayout>
+}