@octane-xplat/ui 0.6.0 → 0.7.1

package/src/store.mobile.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from 'vitest'
+import {
+	createContext,
+	createObjectContainer,
+	createObjectDriver,
+	createUniversalRoot,
+	defineUniversalComponent,
+	flushUniversalSync,
+	universalComponent,
+	universalPlan,
+	universalValue,
+	useContext,
+} from 'octane/universal/native'
+
+import { createStore } from './store'
+import { useStore } from './use-store'
+
+// Universal-runtime scheduler semantics, exercised through the object driver
+// (the same retain/dirty-epoch path the NativeScript driver runs). These tests
+// pin the deliberate divergence from the DOM renderer: a re-rendering parent
+// retains children whose props are shallow-unchanged, so module-store reads
+// only refresh in components that subscribe themselves — via useStore.
+
+const labelPlan = universalPlan('object', {
+	kind: 'host',
+	type: 'label',
+	bindings: [['value', 0]],
+})
+
+const label = (value: string) => universalValue(labelPlan, [value])
+const texts = (container: ReturnType<typeof createObjectContainer>) =>
+	container.children.map((c: any) => c.props.value)
+
+function objectRoot() {
+	const container = createObjectContainer()
+	return { container, root: createUniversalRoot(container, createObjectDriver()) }
+}
+
+describe('universal renderer — store reads under parent re-render', () => {
+	it('refreshes a child that reads the store through useStore', () => {
+		const store = createStore(0)
+		const Child = defineUniversalComponent('object', () => label(`child:${useStore(store)}`))
+		const Parent = defineUniversalComponent('object', () => {
+			useStore(store)
+			return [universalComponent('object', Child, { stable: 'same' }), label('parent')]
+		})
+
+		const { container, root } = objectRoot()
+		root.render(Parent, {})
+		expect(texts(container)).toEqual(['child:0', 'parent'])
+
+		flushUniversalSync(() => store.set(1))
+		expect(texts(container)).toEqual(['child:1', 'parent'])
+		root.unmount()
+	})
+
+	it('retains a child that reads the store bare — the divergence useStore fixes', () => {
+		const store = createStore(0)
+		const renders = { bare: 0, propDriven: 0 }
+		// Bare read: no subscription — a retained child never re-runs.
+		const BareChild = defineUniversalComponent('object', () => {
+			renders.bare++
+			return label(`bare:${store.get()}`)
+		})
+
+		// Control: a child whose PROPS change still re-renders normally.
+		const PropChild = defineUniversalComponent('object', (props: { tick: number }) => {
+			renders.propDriven++
+			return label(`prop:${props.tick}`)
+		})
+
+		const Parent = defineUniversalComponent('object', (props: { tick: number }) => {
+			useStore(store)
+			return [
+				universalComponent('object', BareChild, { stable: 'same' }),
+				universalComponent('object', PropChild, { tick: props.tick }),
+			]
+		})
+
+		const { container, root } = objectRoot()
+		root.render(Parent, { tick: 0 })
+		expect(texts(container)).toEqual(['bare:0', 'prop:0'])
+
+		// Store write: parent re-renders, bare-read child is retained → stale.
+		flushUniversalSync(() => store.set(1))
+		expect(renders.bare).toBe(1)
+		expect(texts(container)).toEqual(['bare:0', 'prop:0'])
+
+		// Changed props still re-render the same child — retention keys on
+		// shallow-equal props, not on component identity alone.
+		root.render(Parent, { tick: 1 })
+		expect(renders.propDriven).toBe(2)
+		expect(renders.bare).toBe(1)
+		expect(texts(container)).toEqual(['bare:0', 'prop:1'])
+		root.unmount()
+	})
+
+	it('re-renders a retained child when its consumed context changes', () => {
+		const Theme = createContext('light')
+		const renders = { ctx: 0, plain: 0 }
+		const CtxChild = defineUniversalComponent('object', () => {
+			renders.ctx++
+			return label(`ctx:${useContext(Theme)}`)
+		})
+
+		const PlainChild = defineUniversalComponent('object', () => {
+			renders.plain++
+			return label('plain')
+		})
+
+		const Parent = defineUniversalComponent('object', (props: { theme: string }) => [
+			universalComponent('object', Theme, {
+				value: props.theme,
+				children: universalComponent('object', CtxChild, { stable: 'same' }),
+			}),
+			universalComponent('object', PlainChild, { stable: 'same' }),
+		])
+
+		const { container, root } = objectRoot()
+		root.render(Parent, { theme: 'light' })
+		expect(texts(container)).toEqual(['ctx:light', 'plain'])
+
+		// Changed provider value defeats retention for consumers only.
+		root.render(Parent, { theme: 'dark' })
+		expect(renders.ctx).toBe(2)
+		expect(renders.plain).toBe(1)
+		expect(texts(container)).toEqual(['ctx:dark', 'plain'])
+		root.unmount()
+	})
+
+	it('useStore with a selector re-renders only when the slice changes', () => {
+		const store = createStore({ a: 0, b: 0 })
+		const renders = { a: 0 }
+		const Child = defineUniversalComponent('object', () => {
+			renders.a++
+			return label(`a:${useStore(store, (s) => s.a)}`)
+		})
+
+		const { container, root } = objectRoot()
+		root.render(Child, {})
+		expect(texts(container)).toEqual(['a:0'])
+
+		flushUniversalSync(() => store.set({ a: 0, b: 1 }))
+		expect(renders.a).toBe(1) // slice unchanged → no re-render
+		flushUniversalSync(() => store.set({ a: 2, b: 1 }))
+		expect(texts(container)).toEqual(['a:2'])
+		root.unmount()
+	})
+})

package/src/store.ts

@@ -0,0 +1,39 @@
+/**
+ * Module-scope store — the shared-state primitive for this stack.
+ *
+ * Why it exists: the universal (native) renderer RETAINS child components
+ * whose props are shallow-unchanged when a parent re-renders — their render
+ * functions do not re-run, so a bare `store.get()` in a child stays stale
+ * (the DOM renderer re-invokes them, React-style). The portable rule is:
+ * every component that reads shared state subscribes to it. The renderer-owned
+ * `use-store` leaves implement that subscription; this file is the hook-free
+ * half, so plain `.ts` is correct.
+ */
+import type { Store } from './props'
+
+export type { ReadableStore, Store } from './props'
+
+export function createStore<T>(initial: T): Store<T> {
+	let value = initial
+	const listeners = new Set<() => void>()
+	return {
+		get: () => value,
+		set(next) {
+			const v = typeof next === 'function' ? (next as (p: T) => T)(value) : next
+			if (Object.is(v, value)) {
+				return
+			}
+
+			value = v
+			for (const l of [...listeners]) {
+				l()
+			}
+		},
+		subscribe(notify) {
+			listeners.add(notify)
+			return () => {
+				listeners.delete(notify)
+			}
+		},
+	}
+}

package/src/store.web.test.tsrx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest';
+import { act, createRoot } from 'octane';
+import { createStore } from './store';
+import { useStore } from './use-store';
+
+// DOM-renderer counterpart to store.mobile.test.ts. Here a parent re-render
+// re-invokes children with unchanged props (React semantics — memo() is the
+// only bail), so a bare store.get() in a child refreshes incidentally. The
+// portable rule is still: readers subscribe via useStore.
+
+const store = createStore(0);
+
+function BareChild() @{
+	<span class="bare">{String(store.get())}</span>
+}
+
+function SubbedChild() @{
+	const v = useStore(store);
+
+	<span class="subbed">{String(v)}</span>
+}
+
+function SelectedChild() @{
+	const v = useStore(store, (s) => s * 10);
+
+	<span class="sel">{String(v)}</span>
+}
+
+function Parent() @{
+	useStore(store);
+
+	<>
+		<BareChild />
+		<SubbedChild />
+		<SelectedChild />
+	</>
+}
+
+describe('createStore + useStore (DOM renderer)', () => {
+	it('parent store subscription re-renders a bare-read child too (DOM semantics)', () => {
+		const el = document.createElement('div');
+		document.body.appendChild(el);
+		const root = createRoot(el);
+		act(() => root.render(<Parent />));
+		expect(el.querySelector('.bare')!.textContent).toBe('0');
+		expect(el.querySelector('.subbed')!.textContent).toBe('0');
+		expect(el.querySelector('.sel')!.textContent).toBe('0');
+
+		act(() => store.set(1));
+		// On DOM the retained child DOES re-run — the divergence this test pins.
+		expect(el.querySelector('.bare')!.textContent).toBe('1');
+		expect(el.querySelector('.subbed')!.textContent).toBe('1');
+		expect(el.querySelector('.sel')!.textContent).toBe('10');
+		root.unmount();
+		el.remove();
+	});
+});

package/src/styled.macos.tsrx

@@ -0,0 +1,23 @@
+import { defineUniversalComponent, universalComponent } from 'octane/universal/native'
+import { cx } from './cx'
+
+/** Compose CSS-backed class names onto an AppKit component factory. */
+export function styled<P extends { className?: any }, V extends Record<string, any>>(
+	Base: (props: P) => any,
+	def: { base?: any; variants?: V },
+) {
+	function Styled(props: P & { [K in keyof V]?: boolean }) {
+		const classes: any[] = [def.base]
+		const rest: any = { ...props }
+		for (const key of Object.keys(def.variants ?? {})) {
+			if ((props as any)[key]) {classes.push((def.variants as any)[key])}
+			delete rest[key]
+		}
+
+		if (props.className) {classes.push(props.className)}
+		rest.className = cx(classes)
+		return universalComponent('macos', Base as any, rest)
+	}
+
+	return defineUniversalComponent('macos', Styled)
+}

package/src/styled.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest'
+import { styled } from './styled.tsrx'
+import { getColorScheme } from './theme/colorScheme.web'
+
+// styled.tsrx builds elements via universalComponent() — a plain
+// {$$kind, component, props:{props,key,hasKey,hasChildren}} object — so
+// composition is node-testable. (Compiled components can't be
+// direct-called for inspection on web — the runtime owns invocation.)
+
+const Base = ((props: any) => props) as any
+const inner = (el: any) => el.props.props
+
+describe('styled() (native leaf)', () => {
+	const Btn = styled(Base, { base: 'btn', variants: { danger: 'bg-danger', flat: 'shadow-none' } })
+
+	it('composes base + variant classes', () => {
+		const el = Btn({ danger: true })
+		expect(inner(el).className).toEqual(['btn', 'bg-danger'])
+		expect(el.component).toBe(Base)
+	})
+
+	it('drops falsy variants and consumes variant props', () => {
+		const el = Btn({ danger: false, flat: true, id: 'b1' })
+		expect(inner(el).className).toEqual(['btn', 'shadow-none'])
+		expect(inner(el).danger).toBeUndefined()
+		expect(inner(el).flat).toBeUndefined()
+		expect(inner(el).id).toBe('b1') // non-variant props pass through
+	})
+
+	it('appends caller className last', () => {
+		const el = Btn({ danger: true, className: 'extra' })
+		expect(inner(el).className).toEqual(['btn', 'bg-danger', 'extra'])
+	})
+})
+
+describe('getColorScheme (web leaf)', () => {
+	it('falls back to light without matchMedia', () => {
+		expect(getColorScheme()).toBe('light')
+	})
+})

package/src/styled.tsrx

@@ -0,0 +1,36 @@
+import { defineUniversalComponent, universalComponent } from 'octane/universal/native';
+
+/**
+ * styled() — decision #7, Tamagui-shaped but CSS-backed. base/variants are
+ * class strings composed into className; the leaf decides what those classes
+ * mean per platform.
+ *
+ *   const DangerBtn = styled(Pressable, { base: 'btn', variants: { danger: 'bg-danger' } });
+ *   <DangerBtn danger />  →  className=['btn','bg-danger']
+ *
+ * Universal constraint (Exp 16): component elements require the
+ * compiler-stamped UNIVERSAL_COMPONENT mark and JSX/`@{ }` only lowers at
+ * module level — so a component factory can't be authored with JSX. This
+ * leaf stamps the mark itself via defineUniversalComponent and returns
+ * universalComponent(...) elements directly. If upstream exposes a blessed
+ * factory path, switch to it (driver-level fix candidate).
+ */
+export function styled<P extends { className?: any }, V extends Record<string, any>>(
+	Base: (props: P) => any,
+	def: { base?: any; variants?: V },
+) {
+	function Styled(props: P & { [K in keyof V]?: boolean }) {
+		const cls: any[] = [def.base];
+		const rest: any = { ...props };
+		for (const k of Object.keys(def.variants ?? {})) {
+			if ((props as any)[k]) cls.push((def.variants as any)[k]);
+			delete rest[k]; // variant flags are consumed — don't leak to the leaf
+		}
+
+		if (props.className) cls.push(props.className);
+		rest.className = cls;
+		return universalComponent('nativescript', Base as any, rest);
+	}
+
+	return defineUniversalComponent('nativescript', Styled);
+}

package/src/styled.web.tsrx

@@ -0,0 +1,23 @@
+/**
+ * styled() — decision #7. Web side: DOM codegen lowers JSX in nested
+ * functions fine, so the factory is a plain component.
+ */
+export function styled<P extends { className?: any }, V extends Record<string, any>>(
+	Base: (props: P) => any,
+	def: { base?: any; variants?: V },
+) {
+	function Styled(props: P & { [K in keyof V]?: boolean }) @{
+		const cls: any[] = [def.base];
+		const rest: any = { ...props };
+		for (const k of Object.keys(def.variants ?? {})) {
+			if ((props as any)[k]) cls.push((def.variants as any)[k]);
+			delete rest[k];
+		}
+
+		if (props.className) cls.push(props.className);
+
+		<Base {...rest} className={cls} />
+	}
+
+	return Styled;
+}

package/src/surfaces.macos.tsrx

@@ -0,0 +1,27 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { OverlayProps, PopoverProps, SheetProps } from './props'
+import { cx } from './cx'
+
+export function Overlay(props: OverlayProps) @{
+	@if (props.open) {
+		<flexboxlayout flexDirection="column" className={cx('vx-overlay', props.className)} style={props.style}>
+			{props.children}
+		</flexboxlayout>
+	}
+}
+
+export function Popover(props: PopoverProps) @{
+	@if (props.open) {
+		<flexboxlayout flexDirection="column" className={cx('vx-popover', props.className)} style={props.style}>
+			{props.children}
+		</flexboxlayout>
+	}
+}
+
+export function Sheet(props: SheetProps) @{
+	@if (props.open) {
+		<flexboxlayout flexDirection="column" className={cx('vx-sheet', props.className)} style={props.style}>
+			{props.children}
+		</flexboxlayout>
+	}
+}

package/src/svg.mobile.ts

@@ -0,0 +1,76 @@
+import { registerElement } from '@nativescript-community/octane'
+import type { Attributes } from '@nativescript-community/octane/intrinsics'
+import { SVGView } from './vendor/ui-svg'
+import type { IconGlyph } from './props'
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		svgview: Omit<Attributes<typeof SVGView>, 'src'> & {
+			/** SVGView awaits promise srcs — remote .svg URLs arrive as fetched markup. */
+			src?: string | Promise<string>
+			stretch?: 'none' | 'fill' | 'aspectFit' | 'aspectFill'
+		}
+	}
+}
+
+// Vendored ui-svg SVGView (Icon + Image + Meter route SVG sources here
+// unconditionally): SVGView renders via androidsvg on Android, SVGKit on iOS.
+// Its src grammar is File / ImageAsset / res:// / ~/, or an inline markup
+// string.
+registerElement('svgview', SVGView)
+
+const SVG_DATA_URI = /^data:image\/svg\+xml[;,]/i
+const SVG_PATH = /\.svg([?#].*)?$/i
+const EMPTY_SVG = '<svg xmlns="http://www.w3.org/2000/svg"/>'
+
+/** True when an `src` carries SVG: inline markup, an svg data URI, or an
+ *  .svg path/URL. Anything else stays on the raster <image> path. */
+export function isSvgSrc(src: string): boolean {
+	return src.trimStart().startsWith('<svg') || SVG_DATA_URI.test(src) || SVG_PATH.test(src)
+}
+
+/** Normalize an svg-shaped src into SVGView's grammar: file/resource paths and
+ *  markup pass through, data URIs decode to markup, remote URLs fetch to
+ *  markup (SVGView has no fetch of its own — it awaits promise srcs). */
+export function svgSource(src: string): string | Promise<string> {
+	if (SVG_DATA_URI.test(src)) {
+		const comma = src.indexOf(',')
+		const body = src.slice(comma + 1)
+		if (src.slice(0, comma).endsWith(';base64')) {
+			const atob = (globalThis as { atob?: (data: string) => string }).atob
+			if (!atob) {
+				return EMPTY_SVG
+			}
+
+			return atob(body)
+		}
+
+		return decodeURIComponent(body)
+	}
+
+	if (/^https?:\/\//.test(src)) {
+		return fetch(src)
+			.then((r) => (r.ok ? r.text() : EMPTY_SVG))
+			.catch(() => EMPTY_SVG)
+	}
+
+	return src
+}
+
+/** IconGlyph → a full `<svg>` string for SVGView. `svg` path data gets a
+ *  `<path>` with the requested fill; `markup` wraps inside a viewBox shell
+ *  with `color`/`fill` set on the root so `currentColor` and default-fill
+ *  children pick up the tint. */
+export function glyphSvgMarkup(glyph: IconGlyph, color?: string): string | undefined {
+	const viewBox = glyph.viewBox ?? '0 0 24 24'
+	if (glyph.markup) {
+		const tint = color ? ` color="${color}" fill="${color}"` : ''
+		return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}"${tint}>${glyph.markup}</svg>`
+	}
+
+	if (glyph.svg) {
+		return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${viewBox}"><path d="${glyph.svg}" fill="${color ?? 'currentColor'}"/></svg>`
+	}
+
+	return undefined
+}

package/src/tap-to-blur.mobile.ts

@@ -0,0 +1,108 @@
+import { Application } from '@nativescript/core';
+
+/** Tap-outside-to-blur: iOS keeps a focused UITextField/UITextView as first
+ *  responder until something else takes it, so a tap on blank chrome never
+ *  dismisses the keyboard on its own.
+ *
+ *  iOS: a single window-level UITapGestureRecognizer (ref-counted across
+ *  attach calls) sees every touch in the app window — popups/sheets included —
+ *  where a recognizer on an intermediate container proved unreliable. On each
+ *  tap we hit-test and resign first responder unless the hit view is an
+ *  editable text view (otherwise the field would focus-then-blur in the same
+ *  tap — recognizers fire on touch-up, after the field's touch-down focus).
+ *  Keyboard taps live in a separate UIWindow, so they never reach it.
+ *  `cancelsTouchesInView` stays false so taps still reach buttons.
+ *
+ *  Android: hides the soft keyboard from the currently focused view when a
+ *  tap lands on the attached container. */
+export function attachTapToBlur(view: any): () => void {
+	const marker = '__xplatTapToBlur';
+	if (!view || view[marker]) {return () => {};}
+	view[marker] = true;
+
+	if (Application.ios) {
+		iosAttach();
+		return () => {
+			view[marker] = false;
+			iosDetach();
+		};
+	}
+
+	if (Application.android) {
+		const handler = (_args: any) => {
+			const activity = Application.android.foregroundActivity;
+			const focused = activity?.currentFocus;
+			if (!focused) {return;}
+			const imm = activity.getSystemService(android.content.Context.INPUT_METHOD_SERVICE);
+			imm?.hideSoftInputFromWindow(focused.getWindowToken(), 0);
+		};
+
+		view.on('tap', handler);
+		return () => {
+			view[marker] = false;
+			view.off('tap', handler);
+		};
+	}
+
+	return () => {
+		view[marker] = false;
+	};
+}
+
+let iosCount = 0;
+let iosTarget: any = null;
+let iosRecognizer: any = null;
+let iosWindow: any = null;
+
+function iosAttach() {
+	iosCount++;
+	if (iosRecognizer) {return;}
+	const appWin = appWindow();
+	if (!appWin) {return;}
+	iosWindow = appWin;
+
+	const Owner = class extends NSObject {
+		static ObjCExposedMethods = {
+			tap: { returns: interop.types.void, params: [UITapGestureRecognizer] },
+		};
+		tap(recognizer: any) {
+			const point = recognizer.locationInView(iosWindow);
+			// hitTest can land on a text field's internal subview — walk up.
+			let hit = iosWindow.hitTest(point, null);
+			while (hit) {
+				if (hit instanceof UITextField || hit instanceof UITextView) {return;}
+				hit = hit.superview;
+			}
+
+			iosWindow.endEditing(true);
+		}
+	};
+
+	iosTarget = Owner.new();
+	iosRecognizer = UITapGestureRecognizer.alloc().initWithTargetAction(iosTarget, 'tap');
+	iosRecognizer.cancelsTouchesInView = false;
+	appWin.addGestureRecognizer(iosRecognizer);
+}
+
+function iosDetach() {
+	iosCount--;
+	if (iosCount > 0 || !iosRecognizer) {return;}
+	iosWindow?.removeGestureRecognizer(iosRecognizer);
+	iosRecognizer = null;
+	iosTarget = null;
+	iosWindow = null;
+}
+
+function appWindow() {
+	const scenes = UIApplication.sharedApplication.connectedScenes;
+	// connectedScenes is an NSSet — `allObjects` marshals to a JS array.
+	for (const scene of (scenes as any).allObjects ?? []) {
+		if (scene instanceof UIWindowScene) {
+			for (const w of (scene.windows as any)?.allObjects ?? scene.windows ?? []) {
+				if (w.isKeyWindow) {return w;}
+			}
+		}
+	}
+
+	return UIApplication.sharedApplication.keyWindow;
+}

package/src/text-controls.macos.tsrx

@@ -0,0 +1,11 @@
+/** @jsxImportSource @xplat/macos/renderer */
+import type { TextAreaProps, TextInputProps } from './props'
+import { cx } from './cx'
+
+export function TextInput(props: TextInputProps) @{
+	<textfield id={props.id} value={props.value} placeholder={props.placeholder} className={cx('vx-input', props.className)} style={props.style} onTextChange={props.onChange} accessibilityLabel={props.accessibilityLabel} />
+}
+
+export function TextArea(props: TextAreaProps) @{
+	<textview id={props.id} value={props.value} placeholder={props.placeholder} rows={props.autoGrow ? undefined : props.rows ?? 3} className={cx('vx-textarea', props.className)} style={props.style} onTextChange={props.onChange} accessibilityLabel={props.accessibilityLabel} />
+}

package/src/text-write.ts

@@ -0,0 +1,28 @@
+/** Controlled `text` write for TextInput/TextArea leaves. The driver's
+ *  generic prop path writes view.text verbatim; on Android the EditText
+ *  setText resets the cursor to 0 on every controlled write. Park and
+ *  restore the selection around the write (clamped to the new length so an
+ *  append-shrink can't throw). iOS keeps the plain write — UITextField's
+ *  text setter preserves the selected text range already.
+ *  Returns without writing when the value already matches — the textChange
+ *  echo of the user's own typing must not bounce back through setText. */
+export function writeText(view: any, value: string | undefined | null): void {
+	const next = value ?? ''
+	if (!view || view.text === next) {
+		return
+	}
+
+	const et = view.android
+	if (!et) {
+		view.text = next
+		return
+	}
+
+	const start = et.getSelectionStart?.() ?? -1
+	const end = et.getSelectionEnd?.() ?? -1
+	view.text = next
+	if (start >= 0) {
+		const len = next.length
+		et.setSelection(Math.min(start, len), Math.min(end >= 0 ? end : start, len))
+	}
+}

package/src/text-write.web.ts

@@ -0,0 +1,13 @@
+/** Web twin — controlled text writes are DOM value assignments; the browser
+ *  keeps the selection on unchanged prefixes itself. Present for
+ *  platform-suffix parity; the native leaves are the only callers. */
+export function writeText(view: any, value: string | undefined | null): void {
+	if (!view) {
+		return
+	}
+
+	const next = value ?? ''
+	if (view.text !== next) {
+		view.text = next
+	}
+}