@octane-xplat/ui 0.9.0 → 0.10.0

package/dist/native/query-cache.js

@@ -0,0 +1,358 @@
+import { SIGNAL_BINDING_IDENTITY, SIGNAL_BINDING_READ, SIGNAL_BINDING_SUBSCRIBE, SIGNAL_HANDLE, ScopeDisposedError, __enableUniversalSignalDocument, __queryAt } from "octane/signals";
+//#region src/query-cache.ts
+__enableUniversalSignalDocument(1);
+/** Deterministic JSON encoding: sorted object fields, JSON scalar rules. */
+function canonicalize(value) {
+	if (value === void 0 || value === null) return "null";
+	switch (typeof value) {
+		case "boolean":
+		case "string": return JSON.stringify(value);
+		case "number": return Number.isFinite(value) ? JSON.stringify(value) : "null";
+		case "object": {
+			if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`;
+			const prototype = Object.getPrototypeOf(value);
+			if (prototype !== null && prototype !== Object.prototype) throw new TypeError("query cache keys and selections must be JSON-serializable");
+			return `{${Object.keys(value).sort().filter((field) => value[field] !== void 0).map((field) => `${JSON.stringify(field)}:${canonicalize(value[field])}`).join(",")}}`;
+		}
+		default: throw new TypeError("query cache keys and selections must be JSON-serializable");
+	}
+}
+var SEPARATOR = "
";
+function elementsOf(key) {
+	return key.map(canonicalize);
+}
+function keyString(elements) {
+	return elements.join(SEPARATOR);
+}
+function isPrefix(prefix, elements) {
+	if (prefix.length > elements.length) return false;
+	for (let i = 0; i < prefix.length; i++) if (prefix[i] !== elements[i]) return false;
+	return true;
+}
+function elementsEqual(a, b) {
+	return a.length === b.length && isPrefix(a, b);
+}
+var families = /* @__PURE__ */ new Map();
+var entries = /* @__PURE__ */ new Map();
+function familyFor(key) {
+	const elements = elementsOf(key);
+	if (elements.length === 0) throw new TypeError("cachedQuery$ requires a non-empty key");
+	const id = keyString(elements);
+	let family = families.get(id);
+	if (family === void 0) {
+		family = {
+			elements,
+			queries: /* @__PURE__ */ new Map()
+		};
+		families.set(id, family);
+	}
+	return family;
+}
+function entryFor(elements, persist) {
+	const id = keyString(elements);
+	let entry = entries.get(id);
+	if (entry === void 0) {
+		entry = {
+			elements,
+			value: void 0,
+			hasValue: false,
+			fetchedAt: 0,
+			invalidated: false,
+			inflight: void 0,
+			controller: void 0,
+			persistChecked: false,
+			persist
+		};
+		entries.set(id, entry);
+	} else if (persist !== void 0) entry.persist = persist;
+	return entry;
+}
+function matchingElements(key, exact) {
+	if (key === void 0) return () => true;
+	const elements = elementsOf(key);
+	return (candidate) => exact ? candidate.length === elements.length && isPrefix(elements, candidate) : isPrefix(elements, candidate);
+}
+var loadMode = "normal";
+function withLoadMode(mode, run) {
+	const previous = loadMode;
+	loadMode = mode;
+	try {
+		return run();
+	} finally {
+		loadMode = previous;
+	}
+}
+/**
+* Retry every registered cached query whose last-selected cache key matches,
+* in `normal` mode so entry staleness decides whether each one fetches.
+* Queries that never loaded a selection are skipped — a fan-out must not wake
+* unevaluated cells into requests nobody made. A disposed declaration owner
+* is unregistered; other failures land on the query cell's own error state
+* and must not stop the fan-out.
+*/
+function republish(mode, matches) {
+	for (const family of families.values()) for (const [registration, query] of [...family.queries]) {
+		const selected = query.state.lastElements;
+		if (selected === void 0 || !matches(selected)) continue;
+		try {
+			withLoadMode(mode, () => query.facade.republishRetry());
+		} catch (error) {
+			if (error instanceof ScopeDisposedError) family.queries.delete(registration);
+		}
+	}
+}
+function storageKey(scope, entry) {
+	return `xplat:query:${scope}:${keyString(entry.elements)}`;
+}
+function persistWrite(entry) {
+	const persist = entry.persist;
+	if (persist === void 0 || !entry.hasValue) return;
+	let scope;
+	try {
+		scope = persist.scope?.() ?? null;
+	} catch {
+		return;
+	}
+	if (scope === null) return;
+	const envelope = JSON.stringify({
+		v: persist.version,
+		t: entry.fetchedAt,
+		d: entry.value
+	});
+	try {
+		Promise.resolve(persist.storage.set(storageKey(scope, entry), envelope)).catch(() => {});
+	} catch {}
+}
+async function restoreEntry(entry) {
+	entry.persistChecked = true;
+	const persist = entry.persist;
+	if (persist === void 0) return;
+	let scope;
+	try {
+		scope = persist.scope?.() ?? null;
+	} catch {
+		return;
+	}
+	if (scope === null) return;
+	let raw;
+	try {
+		raw = await persist.storage.get(storageKey(scope, entry));
+	} catch {
+		return;
+	}
+	if (raw == null) return;
+	try {
+		const envelope = JSON.parse(raw);
+		if (envelope === null || typeof envelope !== "object" || envelope.v !== persist.version || typeof envelope.t !== "number" || persist.maxAge !== void 0 && Date.now() - envelope.t > persist.maxAge) throw new Error("stale envelope");
+		entry.value = envelope.d;
+		entry.hasValue = true;
+		entry.fetchedAt = envelope.t;
+	} catch {
+		try {
+			await persist.storage.remove(storageKey(scope, entry));
+		} catch {}
+	}
+}
+function removePersisted(entry) {
+	const persist = entry.persist;
+	if (persist === void 0) return;
+	let scope;
+	try {
+		scope = persist.scope?.() ?? null;
+	} catch {
+		return;
+	}
+	if (scope === null) return;
+	try {
+		Promise.resolve(persist.storage.remove(storageKey(scope, entry))).catch(() => {});
+	} catch {}
+}
+function startFetch(entry, selection, load, previous) {
+	if (entry.inflight !== void 0) return entry.inflight;
+	const controller = new AbortController();
+	entry.controller = controller;
+	const context = previous === void 0 ? { signal: controller.signal } : {
+		signal: controller.signal,
+		previous
+	};
+	const request = Promise.resolve().then(() => load(selection, context));
+	entry.inflight = request;
+	request.then((value) => {
+		if (entry.inflight !== request) return;
+		entry.inflight = void 0;
+		entry.controller = void 0;
+		entry.value = value;
+		entry.hasValue = true;
+		entry.invalidated = false;
+		entry.fetchedAt = Date.now();
+		persistWrite(entry);
+		republish("serve", (elements) => elementsEqual(elements, entry.elements));
+	}, () => {
+		if (entry.inflight !== request) return;
+		entry.inflight = void 0;
+		entry.controller = void 0;
+	});
+	return request;
+}
+function loadThroughCache(elements, options, load, selection, context) {
+	const entry = entryFor(elements, options?.persist);
+	const staleTime = options?.staleTime ?? 0;
+	const mode = loadMode;
+	if (entry.inflight !== void 0) return entry.inflight;
+	if (entry.hasValue) {
+		if (mode === "serve") return entry.value;
+		const timeStale = staleTime !== Number.POSITIVE_INFINITY && Date.now() - entry.fetchedAt >= staleTime;
+		if (!(entry.invalidated || timeStale) && mode !== "forced") return entry.value;
+		if (mode === "forced" || context.previous !== void 0) return startFetch(entry, selection, load, context.previous ?? entry.value);
+		startFetch(entry, selection, load, entry.value).catch(() => {});
+		return entry.value;
+	}
+	if (!entry.persistChecked && entry.persist !== void 0) return (async () => {
+		await restoreEntry(entry);
+		if (entry.hasValue) {
+			const timeStale = staleTime !== Number.POSITIVE_INFINITY && Date.now() - entry.fetchedAt >= staleTime;
+			if (!entry.invalidated && !timeStale) return entry.value;
+			startFetch(entry, selection, load, entry.value).catch(() => {});
+			return entry.value;
+		}
+		return startFetch(entry, selection, load, context.previous);
+	})();
+	return startFetch(entry, selection, load, context.previous);
+}
+/**
+* Declare a `query$` whose results are shared through the module-level query
+* cache. Same signature shape as `query$`, plus a required family `key` that
+* gives the query a stable cross-screen identity and an invalidation target.
+*
+* The returned handle is a full `QuerySignal`: `.get()` suspends, `.latest()`
+* and `.snapshot()` read without suspending, and `.refetch()`/`.retry()`/
+* `.reset()` force a fresh request.
+*
+* The inner query uses an explicit, family-derived key so every re-render
+* declaration resolves to the same cell. Two declarations in the same scope
+* that share a family therefore also share a cell — the first selector and
+* loader bound in that scope wins, the same as declaring the same `query$`
+* twice. To keep same-family declarations distinct inside one scope, pass a
+* distinguishing `options.key`.
+*/
+function cachedQuery$(key, select, load, options) {
+	if (options !== void 0 && options.kind !== void 0) throw new TypeError("cachedQuery$ supports promise queries only; stream queries stay plain query$");
+	const family = familyFor(key);
+	const state = { lastElements: void 0 };
+	const handle = new CachedQuerySignal();
+	const inner$ = __queryAt("i:90ea7b73", select, (selection, context) => {
+		const elements = [...family.elements, canonicalize(selection)];
+		state.lastElements = elements;
+		return loadThroughCache(elements, options, load, selection, context);
+	}, { key: `xplat:query-cache:${keyString(family.elements)}${options?.key ? `:${options.key}` : ""}` });
+	handle.inner$ = inner$;
+	const registration = registrationKey(inner$);
+	const existing = family.queries.get(registration);
+	if (existing === void 0) family.queries.set(registration, {
+		facade: handle,
+		state
+	});
+	else existing.facade = handle;
+	return handle;
+}
+/**
+* One registration per (node key, declaring owner): a component re-declaring
+* the same cached query on every render reuses its registration, while two
+* mounted instances or two roots register side by side. The declaring
+* owner is read off the compiled descriptor's `instanceOwner` — a patched-
+* octane internal — with the scope key as discriminator.
+*/
+function registrationKey(inner$) {
+	const owner = inner$.instanceOwner;
+	const discriminator = owner !== null && typeof owner === "object" ? owner.instanceKey ?? owner.scopeKey : void 0;
+	return `${inner$.key}${discriminator ?? ""}`;
+}
+var CachedQuerySignal = class {
+	constructor() {
+		this[SIGNAL_HANDLE] = true;
+		this.kind = "async";
+	}
+	get key() {
+		return this.inner$.key;
+	}
+	forced(run) {
+		withLoadMode("forced", run);
+	}
+	/** @internal Fan-out retries inherit the republish mode instead of forcing. */
+	republishRetry() {
+		this.inner$.retry();
+	}
+	get() {
+		return this.inner$.get();
+	}
+	latest(fallback) {
+		return this.inner$.latest(fallback);
+	}
+	snapshot() {
+		return this.inner$.snapshot();
+	}
+	subscribe(notify) {
+		return this.inner$.subscribe(notify);
+	}
+	[SIGNAL_BINDING_READ]() {
+		return this.inner$[SIGNAL_BINDING_READ]();
+	}
+	[SIGNAL_BINDING_SUBSCRIBE](notify, onRetire) {
+		return this.inner$[SIGNAL_BINDING_SUBSCRIBE](notify, onRetire);
+	}
+	[SIGNAL_BINDING_IDENTITY]() {
+		return this.inner$[SIGNAL_BINDING_IDENTITY]();
+	}
+	refetch() {
+		this.forced(() => this.inner$.refetch());
+	}
+	retry(options) {
+		this.forced(() => this.inner$.retry(options));
+	}
+	reset() {
+		this.forced(() => this.inner$.reset());
+	}
+};
+/**
+* Mark matching cache entries stale and refetch every live query that can own
+* them. Call with no key to invalidate the whole cache.
+*
+* Owners refetch through their own query cell, so screens keep their current
+* data while the new request runs (`snapshot().refreshing`). Entries whose
+* owners are unmounted stay stale; their next reader revalidates.
+*/
+function invalidateQueries(key, options) {
+	const matches = matchingElements(key, options?.exact === true);
+	for (const entry of entries.values()) if (matches(entry.elements)) entry.invalidated = true;
+	republish("normal", matches);
+}
+/**
+* Evict matching cache entries — and their persisted records — without
+* refetching. Mounted queries keep the data they already show; the next
+* reader repopulates. Call with no key to clear the whole cache (e.g. on
+* sign-out, before the auth scope changes).
+*/
+function clearQueryCache(key, options) {
+	const matches = matchingElements(key, options?.exact === true);
+	for (const entry of [...entries.values()]) {
+		if (!matches(entry.elements)) continue;
+		entry.controller?.abort();
+		removePersisted(entry);
+		entries.delete(keyString(entry.elements));
+	}
+}
+/** Map-backed storage adapter — tests, examples, and custom persistence hosts. */
+function createMemoryQueryStorage() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		get: (key) => store.get(key) ?? null,
+		set: (key, value) => {
+			store.set(key, value);
+		},
+		remove: (key) => {
+			store.delete(key);
+		}
+	};
+}
+//#endregion
+export { cachedQuery$, clearQueryCache, createMemoryQueryStorage, invalidateQueries };

package/dist/native/query-storage.js

@@ -0,0 +1,30 @@
+import { ApplicationSettings } from "@nativescript/core";
+//#region src/query-storage.ts
+/**
+* Default query persistence adapter on iOS/Android — NativeScript
+* `ApplicationSettings` (NSUserDefaults/SharedPreferences). Synchronous and
+* suitable for bounded JSON snapshots; keep persisted query payloads small.
+* A file-backed adapter remains the upgrade path for larger caches — supply
+* it via `persist.storage`.
+*/
+var platformQueryStorage = {
+	get: (key) => {
+		try {
+			return ApplicationSettings.getString(key) ?? null;
+		} catch {
+			return null;
+		}
+	},
+	set: (key, value) => {
+		try {
+			ApplicationSettings.setString(key, value);
+		} catch {}
+	},
+	remove: (key) => {
+		try {
+			ApplicationSettings.remove(key);
+		} catch {}
+	}
+};
+//#endregion
+export { platformQueryStorage };

package/dist/native/ref-list.js

@@ -0,0 +1,19 @@
+//#region src/ref-list.ts
+function refList(...refs) {
+	const list = [];
+	const collect = (ref) => {
+		if (Array.isArray(ref)) for (const nested of ref) collect(nested);
+		else if (ref != null) list.push(ref);
+	};
+	for (const ref of refs) collect(ref);
+	return list;
+}
+function mergedRef(...refs) {
+	const list = refList(...refs);
+	return (instance) => {
+		for (const ref of list) if (typeof ref === "function") ref(instance);
+		else ref.current = instance;
+	};
+}
+//#endregion
+export { mergedRef, refList };

package/dist/native/relative-position.js

@@ -0,0 +1,7 @@
+//#region src/relative-position.ts
+/** View-relative DIP coordinates for native overlay placement. */
+function relativePosition(view, relativeTo) {
+	return view?.getLocationRelativeTo?.(relativeTo);
+}
+//#endregion
+export { relativePosition };

package/dist/native/resize-basis.js

@@ -0,0 +1,28 @@
+import { Application, Screen } from "@nativescript/core";
+//#region src/resize-basis.ts
+/** Native basis — the `containerRef` view's measured size when supplied,
+*  else the device screen. `layoutChanged` on the container tracks bounds;
+*  orientation changes re-measure the screen fallback. */
+var nativeBasisSource = {
+	storagePrefix: "astryx-resizable:",
+	measure: (containerRef, direction) => {
+		const view = containerRef?.current;
+		if (view) {
+			const size = view.getActualSize?.();
+			const v = direction === "horizontal" ? size?.width : size?.height;
+			return v != null && v > 0 ? v : null;
+		}
+		return direction === "horizontal" ? Screen.mainScreen.widthDIPs : Screen.mainScreen.heightDIPs;
+	},
+	observe: (containerRef, _direction, cb) => {
+		const view = containerRef?.current;
+		if (view) {
+			view.on?.("layoutChanged", cb);
+			return () => view.off?.("layoutChanged", cb);
+		}
+		Application.on("orientationChanged", cb);
+		return () => Application.off("orientationChanged", cb);
+	}
+};
+//#endregion
+export { nativeBasisSource };

package/dist/native/resize-math.js

@@ -0,0 +1,85 @@
+//#region src/resize-math.ts
+/**
+* Resizable size math — 1:1 port of Astryx's parse/toPixels/clamp helpers.
+* Pixel and percentage size constructors plus the basis-resolving and
+* clamping used by the hook.
+*/
+/** An exact pixel/dip size — `pixel(240)`. */
+function pixel(value) {
+	return {
+		type: "pixel",
+		value
+	};
+}
+/** A percentage with exactly one pixel bound — `percent(50, {min: pixel(200)})`
+*  means 50% of the basis, not below 200px. Throws on out-of-range or
+*  conflicting inputs like upstream. */
+function percent(value, constraint) {
+	if (!Number.isFinite(value) || value < 0 || value > 100) throw new Error(`percent(): value must be a number in [0, 100], received ${String(value)}`);
+	if (!constraint || "min" in constraint === "max" in constraint) throw new Error("percent(): supply exactly one of { min: pixel(px) } or { max: pixel(px) }");
+	const bound = "min" in constraint ? constraint.min : constraint.max;
+	if (bound.type !== "pixel" || !Number.isFinite(bound.value) || bound.value < 0) throw new Error("percent(): the bound must be pixel(px) with a non-negative finite number");
+	return "min" in constraint ? {
+		type: "percent",
+		value,
+		min: bound
+	} : {
+		type: "percent",
+		value,
+		max: bound
+	};
+}
+function isPixelSize(v) {
+	return typeof v === "object" && v !== null && v.type === "pixel";
+}
+function isPercentSize(v) {
+	return typeof v === "object" && v !== null && v.type === "percent";
+}
+/**
+* Resolve a ResizableSize to a pixel value.
+* @param basis The pixel size of the reference container/viewport, used for
+*   percentage sizes and bounds. Returns null when the size cannot resolve.
+*/
+function toPixels(size, basis) {
+	if (size == null) return null;
+	if (typeof size === "number") return size;
+	if (typeof size === "string") {
+		const trimmed = size.trim();
+		if (trimmed.endsWith("px")) {
+			const n = parseFloat(trimmed);
+			return Number.isFinite(n) ? n : null;
+		}
+		if (trimmed.endsWith("%")) {
+			const pct = parseFloat(trimmed);
+			return Number.isFinite(pct) ? pct / 100 * basis : null;
+		}
+		const n = parseFloat(trimmed);
+		return Number.isFinite(n) ? n : null;
+	}
+	if (isPixelSize(size)) return size.value;
+	if (isPercentSize(size)) {
+		const px = size.value / 100 * basis;
+		if ("min" in size && size.min) return Math.max(px, size.min.value);
+		if ("max" in size && size.max) return Math.min(px, size.max.value);
+		return px;
+	}
+	return null;
+}
+/** Clamp a size to [min, max] then snap to the nearest configured snap
+*  point. Snaps always win — the panel can only rest at snap values. */
+function clampSize(size, minPx, maxPx, snaps) {
+	const clamped = Math.max(minPx, Math.min(size, maxPx));
+	if (snaps.length === 0) return clamped;
+	let nearest = snaps[0];
+	let dist = Math.abs(clamped - snaps[0]);
+	for (let i = 1; i < snaps.length; i++) {
+		const d = Math.abs(clamped - snaps[i]);
+		if (d < dist) {
+			dist = d;
+			nearest = snaps[i];
+		}
+	}
+	return nearest;
+}
+//#endregion
+export { clampSize, isPercentSize, isPixelSize, percent, pixel, toPixels };

package/dist/native/resize-persist.js

@@ -0,0 +1,25 @@
+import { ApplicationSettings } from "@nativescript/core";
+//#region src/resize-persist.ts
+function loadResizableState(key) {
+	try {
+		if (!ApplicationSettings.hasKey(key)) return null;
+		const raw = ApplicationSettings.getString(key);
+		if (raw == null) return null;
+		const parsed = JSON.parse(raw);
+		if (typeof parsed === "number") return { size: parsed };
+		if (typeof parsed === "object" && parsed !== null) return {
+			size: typeof parsed.size === "number" ? parsed.size : null,
+			isCollapsed: parsed.isCollapsed === true
+		};
+		return null;
+	} catch {
+		return null;
+	}
+}
+function persistResizableState(key, state) {
+	try {
+		ApplicationSettings.setString(key, JSON.stringify(state));
+	} catch {}
+}
+//#endregion
+export { loadResizableState, persistResizableState };