@gadxr/ui 0.0.0-stage → 0.1.0

package/dist/Tooltip.svelte

@@ -0,0 +1,174 @@
+<script lang="ts">import { ensure3d } from "./aframe";
+import { watchTextSize } from "./aframe/measure";
+import { tooltipOffset } from "./component-style";
+import { getDimension, getTheme } from "./context";
+import { font3d } from "./fonts";
+import { createStack, setStack, useSlot } from "./layout.svelte";
+const theme = getTheme();
+let { content, children, placement = "top", open = $bindable(false), delay = theme().tooltip.delay, dimension, style: userStyle = "", ...rest } = $props();
+const t = $derived(theme());
+const tk = $derived(t.tooltip);
+const c = $derived(t.colors.tooltip);
+const font = $derived(t.typography[tk.typography]);
+const contextDimension = getDimension();
+// svelte-ignore state_referenced_locally
+const is3d = (dimension ?? contextDimension) === "3d";
+const id = `ui-tooltip-${Math.random().toString(36).slice(2, 9)}`;
+let timer;
+function show(now = false) {
+	clearTimeout(timer);
+	if (now || delay <= 0) open = true;
+	else timer = setTimeout(() => open = true, delay);
+}
+function hide() {
+	clearTimeout(timer);
+	open = false;
+}
+$effect(() => () => clearTimeout(timer));
+$effect(() => {
+	if (!open) return;
+	const onkey = (event) => event.key === "Escape" && hide();
+	window.addEventListener("keydown", onkey);
+	return () => window.removeEventListener("keydown", onkey);
+});
+// ---- 3D ----
+const m = (px) => px * t.space3d.metersPerPx;
+if (is3d) ensure3d();
+// The trigger lays out in a stack of its own, which tells us its size; this takes its
+// place in the parent's layout like the trigger would have.
+const stack = is3d ? createStack(() => ({
+	direction: "row",
+	gap: 0,
+	align: "center"
+})) : undefined;
+const slot = is3d ? useSlot(() => stack.size) : () => ({
+	x: 0,
+	y: 0
+});
+setStack(stack);
+let textEl = $state();
+let textSize = $state({
+	width: 0,
+	height: 0
+});
+$effect(() => {
+	if (textEl) return watchTextSize(textEl, (width, height) => textSize = {
+		width,
+		height
+	});
+});
+const bubble = $derived({
+	width: textSize.width + 2 * m(tk.paddingX),
+	height: textSize.height + 2 * m(tk.paddingY)
+});
+const at = $derived(tooltipOffset(placement, stack?.size ?? {
+	width: 0,
+	height: 0
+}, bubble, m(tk.gap)));
+// In front of the trigger (and a hovered, lifted button), so nothing covers it.
+const lift = $derived(t.space3d.depth + t.space3d.pressDepth + .01);
+const bubbleDepth = .008;
+</script>
+
+{#if is3d}
+	<!-- svelte-ignore a11y_no_static_element_interactions, a11y_mouse_events_have_key_events -->
+	<a-entity {...rest} onmouseenter={() => show()} onmouseleave={hide}>
+		<a-entity position="{slot().x} {slot().y} 0">
+			<!-- Hover target for triggers that aren't interactive themselves (an Avatar, a Tag):
+			     the cursor only reports .raycastable meshes. Just behind the trigger, so a
+			     Button in front still gets its own hover and clicks. -->
+			<a-entity
+				class="raycastable"
+				geometry="primitive: plane; width: {stack?.size.width ?? 0}; height: {stack?.size.height ?? 0}"
+				material="visible: false"
+				position="0 0 -0.002"
+			></a-entity>
+			{@render children()}
+			<!-- Always there (hidden), so its text is measured before it first shows. Not raycastable,
+			     so it never takes the hover from its trigger. -->
+			<a-entity visible={open && textSize.width > 0} position="{at.x} {at.y} {lift}">
+				<a-entity
+					rounded="width: {bubble.width}; height: {bubble.height}; depth: {bubbleDepth}; radius: {Math.min(m(tk.radius), bubble.height / 2)}; color: {c.fill}"
+					position="{-bubble.width / 2} {-bubble.height / 2} 0"
+				></a-entity>
+				<a-entity
+					bind:this={textEl}
+					troika-text="value: {content.replace(/;/g, ',')}; fontSize: {m(font.fontSize) * t.space3d.textScale}; lineHeight: {font.lineHeight / font.fontSize}; maxWidth: {m(tk.maxWidth)}; color: {c.text}; font: {font3d(t)}; anchor: center; baseline: center; align: center"
+					troika-text-material="shader: standard"
+					position="0 0 {bubbleDepth + 0.002}"
+				></a-entity>
+			</a-entity>
+		</a-entity>
+	</a-entity>
+{:else}
+	<!-- svelte-ignore a11y_no_static_element_interactions -->
+	<span
+		class="ui-tooltip"
+		aria-describedby={open ? id : undefined}
+		onmouseenter={() => show()}
+		onmouseleave={hide}
+		onfocusin={() => show(true)}
+		onfocusout={hide}
+		style={userStyle as string}
+		{...rest}
+	>
+		{@render children()}
+		{#if open}
+			<span
+				{id}
+				role="tooltip"
+				class="bubble"
+				data-placement={placement}
+				style="--ui-fill: {c.fill}; --ui-text: {c.text}; --ui-pad: {tk.paddingY}px {tk.paddingX}px; --ui-radius: {tk.radius}px; --ui-gap: {tk.gap}px; --ui-max: {tk.maxWidth}px; --ui-font: {font.fontWeight} {font.fontSize}px/{font.lineHeight}px {t.typography.fontFamily};"
+			>
+				{content}
+			</span>
+		{/if}
+	</span>
+{/if}
+
+<style>
+	.ui-tooltip {
+		position: relative;
+		display: inline-flex;
+	}
+	.bubble {
+		position: absolute;
+		z-index: 1100;
+		width: max-content;
+		max-width: var(--ui-max);
+		padding: var(--ui-pad);
+		border-radius: var(--ui-radius);
+		background: var(--ui-fill);
+		color: var(--ui-text);
+		font: var(--ui-font);
+		text-align: center;
+		pointer-events: none;
+		animation: ui-tooltip-in 0.12s ease-out;
+	}
+	[data-placement='top'] {
+		bottom: calc(100% + var(--ui-gap));
+		left: 50%;
+		translate: -50% 0;
+	}
+	[data-placement='bottom'] {
+		top: calc(100% + var(--ui-gap));
+		left: 50%;
+		translate: -50% 0;
+	}
+	[data-placement='left'] {
+		right: calc(100% + var(--ui-gap));
+		top: 50%;
+		translate: 0 -50%;
+	}
+	[data-placement='right'] {
+		left: calc(100% + var(--ui-gap));
+		top: 50%;
+		translate: 0 -50%;
+	}
+	@keyframes ui-tooltip-in {
+		from {
+			opacity: 0;
+		}
+	}
+</style>

package/dist/Tooltip.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+import type { Dimension, TooltipPlacement } from './theme';
+type Props = {
+    content: string;
+    children: Snippet;
+    placement?: TooltipPlacement;
+    open?: boolean;
+    delay?: number;
+    dimension?: Dimension;
+    [attribute: string]: unknown;
+};
+declare const Tooltip: import("svelte").Component<Props, {}, "open">;
+type Tooltip = ReturnType<typeof Tooltip>;
+export default Tooltip;

package/dist/aframe/frame.d.ts

@@ -0,0 +1 @@
+export declare function everyFrame(scene: any, callback: () => void): () => void;

package/dist/aframe/frame.js

@@ -0,0 +1,37 @@
+// Runs `callback` once per rendered frame until the returned stop() is called.
+// While an immersive XR session is running, the page's requestAnimationFrame is paused
+// (frames come from the session instead), so this uses the session's loop then, switching
+// when VR starts or ends mid-loop.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export function everyFrame(scene, callback) {
+    let stopped = false;
+    let id = 0;
+    let source = globalThis;
+    const loop = () => {
+        if (stopped)
+            return;
+        callback();
+        schedule();
+    };
+    const schedule = () => {
+        source = scene?.xrSession ?? globalThis;
+        id = source.requestAnimationFrame(loop);
+    };
+    // A frame queued on the page loop just before entering VR would never run (and one on
+    // the session loop dies with the session), so switch loops when VR starts or ends.
+    const reschedule = () => {
+        if (stopped)
+            return;
+        source.cancelAnimationFrame?.(id);
+        schedule();
+    };
+    schedule();
+    scene?.addEventListener?.('enter-vr', reschedule);
+    scene?.addEventListener?.('exit-vr', reschedule);
+    return () => {
+        stopped = true;
+        source.cancelAnimationFrame?.(id);
+        scene?.removeEventListener?.('enter-vr', reschedule);
+        scene?.removeEventListener?.('exit-vr', reschedule);
+    };
+}

package/dist/aframe/index.d.ts

@@ -0,0 +1 @@
+export declare function ensure3d(): void;

package/dist/aframe/index.js

@@ -0,0 +1,19 @@
+// Gets the page's A-Frame ready for the design system's 3D components.
+import { registerPlacement } from './placement';
+import { registerRounded } from './rounded';
+import { TROIKA_SCRIPT } from './scene';
+let checkedTroika = false;
+// `rounded`, `ui-follow` and `ui-attach` ship with the library and are registered here. `troika-text` can't be
+// bundled without pulling in a second copy of three.js / A-Frame, so it's loaded as a script:
+// <Scene3D> adds it if the page didn't (otherwise load aframe-troika-text after A-Frame).
+export function ensure3d() {
+    registerRounded();
+    registerPlacement();
+    if (checkedTroika)
+        return;
+    checkedTroika = true;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (!globalThis.AFRAME.components['troika-text']) {
+        console.error(`gadxr ui: 3D labels need the A-Frame troika-text component. Add <script src="${TROIKA_SCRIPT}"></script> after A-Frame.`);
+    }
+}

package/dist/aframe/measure.d.ts

@@ -0,0 +1,3 @@
+export declare function watchTextLayout(el: HTMLElement, onLayout: (info: any) => void): () => void;
+export declare function watchTextSize(el: HTMLElement, onSize: (width: number, height: number) => void): () => void;
+export declare function setTroikaValue(el: HTMLElement | undefined, value: string): void;

package/dist/aframe/measure.js

@@ -0,0 +1,42 @@
+// Reports a troika-text entity's layout whenever its text re-syncs: its size (meters),
+// or the whole textRenderInfo (caret positions etc.) for text fields.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export function watchTextLayout(el, onLayout) {
+    const entity = el;
+    let mesh;
+    const report = () => {
+        if (mesh?.textRenderInfo)
+            onLayout(mesh.textRenderInfo);
+    };
+    const attach = () => {
+        mesh = entity.components?.['troika-text']?.troikaTextMesh;
+        if (!mesh)
+            return false;
+        mesh.addEventListener('synccomplete', report);
+        report();
+        return true;
+    };
+    const onInitialized = (event) => {
+        if (event.detail?.name === 'troika-text' && attach()) {
+            el.removeEventListener('componentinitialized', onInitialized);
+        }
+    };
+    if (!attach())
+        el.addEventListener('componentinitialized', onInitialized);
+    return () => {
+        el.removeEventListener('componentinitialized', onInitialized);
+        mesh?.removeEventListener('synccomplete', report);
+    };
+}
+export function watchTextSize(el, onSize) {
+    return watchTextLayout(el, (info) => {
+        const bounds = info.blockBounds;
+        if (bounds)
+            onSize(bounds[2] - bounds[0], bounds[3] - bounds[1]);
+    });
+}
+// Sets troika's text on its own, not through the attribute string: A-Frame splits
+// those on `;`, which a user can type.
+export function setTroikaValue(el, value) {
+    el?.setAttribute('troika-text', 'value', value);
+}

package/dist/aframe/placement.d.ts

@@ -0,0 +1,88 @@
+export type HeadPose = {
+    x: number;
+    y: number;
+    z: number;
+    yaw: number;
+};
+export type FollowOptions = {
+    distance: number;
+    height: number;
+    side: number;
+};
+export declare function followGoal(head: HeadPose, { distance, height, side }: FollowOptions): HeadPose;
+export declare function angleDelta(a: number, b: number): number;
+export declare function needsRecentre(panel: {
+    x: number;
+    y: number;
+    z: number;
+}, head: HeadPose, goal: HeadPose, maxAngle: number, slack?: number): boolean;
+export type VRPlacement = 'world' | 'follow' | 'hand';
+export type DesktopPlacement = 'screen' | 'camera';
+export declare function surfacePlacement({ vr, desktop }: {
+    vr: VRPlacement;
+    desktop: DesktopPlacement;
+}, { immersive, presenting }: {
+    immersive: boolean;
+    presenting: boolean;
+}): VRPlacement | DesktopPlacement;
+export declare const easeStep: (dt: number, timeConstant: number) => number;
+export declare function placementComponents(THREE: any): {
+    follow: {
+        schema: {
+            enabled: {
+                default: boolean;
+            };
+            distance: {
+                type: string;
+                default: number;
+            };
+            height: {
+                type: string;
+                default: number;
+            };
+            side: {
+                type: string;
+                default: number;
+            };
+            maxAngle: {
+                type: string;
+                default: number;
+            };
+            smoothing: {
+                type: string;
+                default: number;
+            };
+        };
+        init(this: any): void;
+        update(this: any, old: any): void;
+        remove(this: any): void;
+        tick(this: any, _t: number, dt: number): void;
+    };
+    attach: {
+        schema: {
+            target: {
+                type: string;
+            };
+            position: {
+                type: string;
+                default: {
+                    x: number;
+                    y: number;
+                    z: number;
+                };
+            };
+            rotation: {
+                type: string;
+                default: {
+                    x: number;
+                    y: number;
+                    z: number;
+                };
+            };
+        };
+        init(this: any): void;
+        update(this: any): void;
+        tick(this: any): void;
+    };
+};
+export declare function registerPlacement(AFRAME?: any): void;

package/dist/aframe/placement.js

@@ -0,0 +1,163 @@
+// Placement components for 3D Surfaces, registered by ensure3d():
+//   ui-follow — "lazy follow": the panel stays put while you look around a little,
+//               then glides back in front of you when it's out of a comfort cone.
+//   ui-attach — copies another entity's pose plus an offset each frame (wrist menus).
+// Both work in world space, so the entity should not be a child of the camera.
+// Erasable TypeScript only — tests import it with Node's type stripping.
+// Where a follow panel wants to be: `distance` in front of the head (level, ignoring
+// pitch), `height` relative to the eyes, `side` to the right; turned to face the head.
+export function followGoal(head, { distance, height, side }) {
+    const forward = { x: -Math.sin(head.yaw), z: -Math.cos(head.yaw) };
+    const right = { x: Math.cos(head.yaw), z: -Math.sin(head.yaw) };
+    return {
+        x: head.x + forward.x * distance + right.x * side,
+        y: head.y + height,
+        z: head.z + forward.z * distance + right.z * side,
+        yaw: head.yaw,
+    };
+}
+// Smallest signed difference b - a between two angles (radians).
+export function angleDelta(a, b) {
+    return Math.atan2(Math.sin(b - a), Math.cos(b - a));
+}
+// True when the panel has drifted far enough from its goal that it should move:
+// outside `maxAngle` (degrees, around the head), or nearer/farther/higher/lower than
+// the goal by more than `slack` meters.
+export function needsRecentre(panel, head, goal, maxAngle, slack = 0.3) {
+    const bearing = (p) => Math.atan2(p.x - head.x, p.z - head.z);
+    const reach = (p) => Math.hypot(p.x - head.x, p.z - head.z);
+    return (Math.abs(angleDelta(bearing(panel), bearing(goal))) > (maxAngle * Math.PI) / 180 ||
+        Math.abs(reach(panel) - reach(goal)) > slack ||
+        Math.abs(panel.y - goal.y) > slack);
+}
+export function surfacePlacement({ vr, desktop }, { immersive, presenting }) {
+    if (!immersive)
+        return desktop;
+    return vr === 'hand' && !presenting ? 'follow' : vr;
+}
+// Fraction of the remaining distance to cover this frame, for exponential easing.
+export const easeStep = (dt, timeConstant) => (timeConstant > 0 ? 1 - Math.exp(-dt / timeConstant) : 1);
+export function placementComponents(THREE) {
+    const v = new THREE.Vector3();
+    const q = new THREE.Quaternion();
+    const e = new THREE.Euler();
+    const m = new THREE.Matrix4();
+    // Sets an object's world position and yaw, whatever its parent's transform.
+    function setWorldPose(obj, x, y, z, yaw) {
+        const parent = obj.parent;
+        v.set(x, y, z);
+        q.setFromEuler(e.set(0, yaw, 0, 'YXZ'));
+        if (parent) {
+            parent.updateWorldMatrix(true, false);
+            parent.worldToLocal(v);
+            const parentQ = new THREE.Quaternion();
+            parent.getWorldQuaternion(parentQ);
+            q.premultiply(parentQ.invert());
+        }
+        obj.position.copy(v);
+        obj.quaternion.copy(q);
+    }
+    const follow = {
+        schema: {
+            enabled: { default: true },
+            distance: { type: 'number', default: 1.2 },
+            height: { type: 'number', default: -0.2 },
+            side: { type: 'number', default: 0 },
+            maxAngle: { type: 'number', default: 30 },
+            // ms; how quickly it catches up once it moves.
+            smoothing: { type: 'number', default: 250 },
+        },
+        init() {
+            this.snap = true;
+            this.moving = false;
+            this.resnap = () => (this.snap = true);
+            this.el.sceneEl?.addEventListener('enter-vr', this.resnap);
+            this.el.sceneEl?.addEventListener('exit-vr', this.resnap);
+        },
+        update(old) {
+            if (this.data.enabled && !old?.enabled)
+                this.snap = true;
+        },
+        remove() {
+            this.el.sceneEl?.removeEventListener('enter-vr', this.resnap);
+            this.el.sceneEl?.removeEventListener('exit-vr', this.resnap);
+        },
+        tick(_t, dt) {
+            const camera = this.el.sceneEl?.camera;
+            if (!this.data.enabled || !camera)
+                return;
+            camera.getWorldPosition(v);
+            camera.getWorldQuaternion(q);
+            e.setFromQuaternion(q, 'YXZ');
+            const head = { x: v.x, y: v.y, z: v.z, yaw: e.y };
+            const goal = followGoal(head, this.data);
+            const obj = this.el.object3D;
+            obj.getWorldPosition(v);
+            const panel = { x: v.x, y: v.y, z: v.z };
+            if (this.snap) {
+                this.snap = false;
+                this.moving = false;
+                this.yaw = goal.yaw;
+                setWorldPose(obj, goal.x, goal.y, goal.z, goal.yaw);
+                return;
+            }
+            if (!this.moving && needsRecentre(panel, head, goal, this.data.maxAngle))
+                this.moving = true;
+            if (!this.moving)
+                return;
+            const k = easeStep(dt || 16, this.data.smoothing);
+            const next = {
+                x: panel.x + (goal.x - panel.x) * k,
+                y: panel.y + (goal.y - panel.y) * k,
+                z: panel.z + (goal.z - panel.z) * k,
+            };
+            this.yaw += angleDelta(this.yaw, goal.yaw) * k;
+            setWorldPose(obj, next.x, next.y, next.z, this.yaw);
+            const left = Math.hypot(goal.x - next.x, goal.y - next.y, goal.z - next.z);
+            if (left < 0.005 && Math.abs(angleDelta(this.yaw, goal.yaw)) < 0.01)
+                this.moving = false;
+        },
+    };
+    const attach = {
+        schema: {
+            target: { type: 'selector' },
+            // Offset in the target's space (meters / degrees).
+            position: { type: 'vec3', default: { x: 0, y: 0.1, z: -0.05 } },
+            rotation: { type: 'vec3', default: { x: -50, y: 0, z: 0 } },
+        },
+        init() {
+            this.offset = new THREE.Matrix4();
+            this.scale = new THREE.Vector3();
+        },
+        update() {
+            const { position: p, rotation: r } = this.data;
+            const rad = THREE.MathUtils.degToRad;
+            this.offset.compose(new THREE.Vector3(p.x, p.y, p.z), new THREE.Quaternion().setFromEuler(new THREE.Euler(rad(r.x), rad(r.y), rad(r.z))), new THREE.Vector3(1, 1, 1));
+        },
+        tick() {
+            const target = this.data.target?.object3D;
+            const obj = this.el.object3D;
+            if (!target)
+                return;
+            // updateWorldMatrix(true, …) includes the ancestors: a rig that moved this frame
+            // (walking, teleport) hasn't had its matrixWorld updated yet, which would leave
+            // us a frame behind — visible jitter on a camera-attached menu while walking.
+            target.updateWorldMatrix(true, false);
+            m.multiplyMatrices(target.matrixWorld, this.offset);
+            if (obj.parent) {
+                obj.parent.updateWorldMatrix(true, false);
+                m.premultiply(new THREE.Matrix4().copy(obj.parent.matrixWorld).invert());
+            }
+            // Keep our own scale; take only position and rotation from the target.
+            m.decompose(obj.position, obj.quaternion, this.scale);
+        },
+    };
+    return { follow, attach };
+}
+export function registerPlacement(AFRAME = globalThis.AFRAME) {
+    const { follow, attach } = placementComponents(AFRAME.THREE);
+    if (!AFRAME.components['ui-follow'])
+        AFRAME.registerComponent('ui-follow', follow);
+    if (!AFRAME.components['ui-attach'])
+        AFRAME.registerComponent('ui-attach', attach);
+}

package/dist/aframe/rounded.d.ts

@@ -0,0 +1,61 @@
+export declare function roundedComponent(THREE: any): {
+    schema: {
+        enabled: {
+            default: boolean;
+        };
+        width: {
+            type: string;
+            default: number;
+        };
+        height: {
+            type: string;
+            default: number;
+        };
+        depth: {
+            type: string;
+            default: number;
+        };
+        radius: {
+            type: string;
+            default: number;
+        };
+        topLeftRadius: {
+            type: string;
+            default: number;
+        };
+        topRightRadius: {
+            type: string;
+            default: number;
+        };
+        bottomLeftRadius: {
+            type: string;
+            default: number;
+        };
+        bottomRightRadius: {
+            type: string;
+            default: number;
+        };
+        color: {
+            type: string;
+            default: string;
+        };
+        opacity: {
+            type: string;
+            default: number;
+        };
+        glass: {
+            type: string;
+            default: boolean;
+        };
+        flat: {
+            type: string;
+            default: boolean;
+        };
+    };
+    init(this: any): void;
+    update(this: any): void;
+    updateOpacity(this: any): void;
+    remove(this: any): void;
+    draw(this: any): any;
+};
+export declare function registerRounded(AFRAME?: any): void;