@realitycollective/iwsdk-uiextensions 0.1.0-preview.0

package/dist/systems/window-system.d.ts

@@ -0,0 +1,455 @@
+/**
+ * UIWindowSystem - wires window chrome, keeps the `WindowManager` in sync
+ * with entities, applies focus ordering and minimize state.
+ *
+ * Reuse over recreation: the panel itself is loaded/rendered by the IWSDK's
+ * `PanelUISystem`; this system only discovers the chrome elements by their
+ * well-known ids and drives them.
+ */
+import { type Entity } from '@iwsdk/core';
+declare const UIWindowSystem_base: import("elics").SystemConstructor<import("elics").SystemSchema, {
+    pendingWindows: {
+        required: (import("elics").Component<{
+            windowId: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            title: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            dockMode: {
+                type: import("@iwsdk/core").Types.Enum;
+                enum: {
+                    readonly WorldLocked: "world-locked";
+                    readonly BodyFollow: "body-follow";
+                    readonly HeadLocked: "head-locked";
+                };
+                default: "world-locked";
+            };
+            movable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            closable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            minimizable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            pinnable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            billboardWhileDragging: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            dragDelay: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            followOffset: {
+                type: import("@iwsdk/core").Types.Vec3;
+                default: [number, number, number];
+            };
+            followSpeed: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            followTolerance: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            focusBias: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            targetWidth: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            targetHeight: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            config: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            maxWidth: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            maxHeight: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            document: {
+                type: import("@iwsdk/core").Types.Object;
+                default: undefined;
+            };
+        }>)[];
+        excluded: import("elics").Component<{
+            appliedDockMode: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            chromeWired: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: false;
+            };
+            homeDockMode: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            homeRegion: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            homePosition: {
+                type: import("@iwsdk/core").Types.Vec3;
+                default: [number, number, number];
+            };
+            homeYaw: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }>[];
+    };
+    windows: {
+        required: (import("elics").Component<{
+            windowId: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            title: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            dockMode: {
+                type: import("@iwsdk/core").Types.Enum;
+                enum: {
+                    readonly WorldLocked: "world-locked";
+                    readonly BodyFollow: "body-follow";
+                    readonly HeadLocked: "head-locked";
+                };
+                default: "world-locked";
+            };
+            movable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            closable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            minimizable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            pinnable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            billboardWhileDragging: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            dragDelay: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            followOffset: {
+                type: import("@iwsdk/core").Types.Vec3;
+                default: [number, number, number];
+            };
+            followSpeed: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            followTolerance: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            focusBias: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            targetWidth: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            targetHeight: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            appliedDockMode: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            chromeWired: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: false;
+            };
+            homeDockMode: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            homeRegion: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            homePosition: {
+                type: import("@iwsdk/core").Types.Vec3;
+                default: [number, number, number];
+            };
+            homeYaw: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            document: {
+                type: import("@iwsdk/core").Types.Object;
+                default: undefined;
+            };
+        }>)[];
+    };
+}, World, import("@iwsdk/core").System<import("elics").SystemSchema, {
+    pendingWindows: {
+        required: (import("elics").Component<{
+            windowId: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            title: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            dockMode: {
+                type: import("@iwsdk/core").Types.Enum;
+                enum: {
+                    readonly WorldLocked: "world-locked";
+                    readonly BodyFollow: "body-follow";
+                    readonly HeadLocked: "head-locked";
+                };
+                default: "world-locked";
+            };
+            movable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            closable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            minimizable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            pinnable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            billboardWhileDragging: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            dragDelay: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            followOffset: {
+                type: import("@iwsdk/core").Types.Vec3;
+                default: [number, number, number];
+            };
+            followSpeed: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            followTolerance: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            focusBias: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            targetWidth: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            targetHeight: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            config: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            maxWidth: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            maxHeight: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            document: {
+                type: import("@iwsdk/core").Types.Object;
+                default: undefined;
+            };
+        }>)[];
+        excluded: import("elics").Component<{
+            appliedDockMode: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            chromeWired: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: false;
+            };
+            homeDockMode: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            homeRegion: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            homePosition: {
+                type: import("@iwsdk/core").Types.Vec3;
+                default: [number, number, number];
+            };
+            homeYaw: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }>[];
+    };
+    windows: {
+        required: (import("elics").Component<{
+            windowId: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            title: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            dockMode: {
+                type: import("@iwsdk/core").Types.Enum;
+                enum: {
+                    readonly WorldLocked: "world-locked";
+                    readonly BodyFollow: "body-follow";
+                    readonly HeadLocked: "head-locked";
+                };
+                default: "world-locked";
+            };
+            movable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            closable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            minimizable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            pinnable: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            billboardWhileDragging: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: true;
+            };
+            dragDelay: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            followOffset: {
+                type: import("@iwsdk/core").Types.Vec3;
+                default: [number, number, number];
+            };
+            followSpeed: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            followTolerance: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            focusBias: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            targetWidth: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+            targetHeight: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            appliedDockMode: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            chromeWired: {
+                type: import("@iwsdk/core").Types.Boolean;
+                default: false;
+            };
+            homeDockMode: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            homeRegion: {
+                type: import("@iwsdk/core").Types.String;
+                default: string;
+            };
+            homePosition: {
+                type: import("@iwsdk/core").Types.Vec3;
+                default: [number, number, number];
+            };
+            homeYaw: {
+                type: import("@iwsdk/core").Types.Float32;
+                default: number;
+            };
+        }> | import("elics").Component<{
+            document: {
+                type: import("@iwsdk/core").Types.Object;
+                default: undefined;
+            };
+        }>)[];
+    };
+}>>;
+export declare class UIWindowSystem extends UIWindowSystem_base {
+    private manager;
+    private entitiesById;
+    private localCamera;
+    init(): void;
+    update(): void;
+    entityFor(windowId: string): Entity | undefined;
+    private adoptWindow;
+    /** Return a window to its home: spawn region, or original placement/mode. */
+    returnHome(entity: Entity): void;
+    /** MIN when open, MAX when minimized - the label names the next action. */
+    private syncMinimizeLabel;
+    private syncPinLabel;
+    private releaseWindow;
+    private wireChrome;
+    private applyMinimized;
+    private documentOf;
+}
+export {};

package/dist/systems/window-system.js

@@ -0,0 +1,244 @@
+/**
+ * UIWindowSystem - wires window chrome, keeps the `WindowManager` in sync
+ * with entities, applies focus ordering and minimize state.
+ *
+ * Reuse over recreation: the panel itself is loaded/rendered by the IWSDK's
+ * `PanelUISystem`; this system only discovers the chrome elements by their
+ * well-known ids and drives them.
+ */
+import { PanelDocument, PanelUI, Vector3, createSystem, } from '@iwsdk/core';
+import { UIDockedTo, UIWindow, UIWindowState } from '../components.js';
+import { WINDOW_CHROME_IDS } from '@realitycollective/webxr-uiextensions';
+import { windowManagerFor } from '../manager-registry.js';
+import { minimizeLabelFor, pinLabelFor, } from '@realitycollective/webxr-uiextensions';
+import { DockMode, isDockMode } from '@realitycollective/webxr-uiextensions';
+let autoId = 0;
+export class UIWindowSystem extends createSystem({
+    pendingWindows: {
+        required: [UIWindow, PanelUI, PanelDocument],
+        excluded: [UIWindowState],
+    },
+    windows: { required: [UIWindow, UIWindowState, PanelDocument] },
+}) {
+    manager;
+    entitiesById = new Map();
+    localCamera = new Vector3();
+    init() {
+        this.manager = windowManagerFor(this.world);
+        this.cleanupFuncs.push(this.queries.pendingWindows.subscribe('qualify', (entity) => {
+            this.adoptWindow(entity);
+        }), this.queries.windows.subscribe('disqualify', (entity) => {
+            this.releaseWindow(entity);
+        }), this.manager.events.on('minimized', ({ id }) => this.applyMinimized(id, true)), this.manager.events.on('restored', ({ id }) => this.applyMinimized(id, false)), this.manager.events.on('minimized', (record) => this.syncMinimizeLabel(record)), this.manager.events.on('restored', (record) => this.syncMinimizeLabel(record)), this.manager.events.on('dockChanged', ({ window }) => {
+            const entity = this.entitiesById.get(window.id);
+            if (entity && entity.getValue(UIWindow, 'dockMode') !== window.dockMode) {
+                entity.setValue(UIWindow, 'dockMode', window.dockMode);
+            }
+            this.syncPinLabel(window);
+        }), this.manager.events.on('dragStarted', (window) => this.syncPinLabel(window)), this.manager.events.on('dragEnded', (window) => this.syncPinLabel(window)));
+    }
+    update() {
+        // Focus bias: nudge each window's document toward the viewer by a small
+        // amount inversely related to focus depth, so overlapping windows resolve
+        // in focus order. Computed in entity-local space so it holds for any
+        // window orientation.
+        for (const entity of this.queries.windows.entities) {
+            const id = entity.getValue(UIWindow, 'windowId');
+            if (!this.manager.has(id)) {
+                continue;
+            }
+            const document = this.documentOf(entity);
+            const object = entity.object3D;
+            if (!document || !object) {
+                continue;
+            }
+            const bias = entity.getValue(UIWindow, 'focusBias');
+            const depth = this.manager.orderOf(id);
+            const amount = bias * Math.max(0, this.manager.count - 1 - depth);
+            if (amount === 0) {
+                document.position.set(0, 0, 0);
+                continue;
+            }
+            this.camera.getWorldPosition(this.localCamera);
+            object.worldToLocal(this.localCamera);
+            if (this.localCamera.lengthSq() === 0) {
+                continue;
+            }
+            document.position.copy(this.localCamera.normalize().multiplyScalar(amount));
+        }
+    }
+    entityFor(windowId) {
+        return this.entitiesById.get(windowId);
+    }
+    adoptWindow(entity) {
+        let id = entity.getValue(UIWindow, 'windowId');
+        if (!id) {
+            id = `uix-window-${autoId++}`;
+            entity.setValue(UIWindow, 'windowId', id);
+        }
+        const title = entity.getValue(UIWindow, 'title');
+        const dockMode = entity.getValue(UIWindow, 'dockMode');
+        this.entitiesById.set(id, entity);
+        if (!this.manager.has(id)) {
+            this.manager.open(id, { title, dockMode });
+        }
+        this.wireChrome(entity, id, title);
+        // Snapshot "home" so the DOCK button can return the window: the spawn
+        // region if it was born docked, otherwise its placement + dock mode.
+        const object = entity.object3D;
+        entity.addComponent(UIWindowState, {
+            chromeWired: true,
+            appliedDockMode: '',
+            homeDockMode: dockMode,
+            homeRegion: entity.hasComponent(UIDockedTo)
+                ? entity.getValue(UIDockedTo, 'regionId')
+                : '',
+            homePosition: object ? [object.position.x, object.position.y, object.position.z] : [0, 0, 0],
+            homeYaw: object ? object.rotation.y : 0,
+        });
+        this.syncPinLabel({ id, dockMode, dragging: false });
+    }
+    /** Return a window to its home: spawn region, or original placement/mode. */
+    returnHome(entity) {
+        const homeRegion = entity.getValue(UIWindowState, 'homeRegion');
+        if (homeRegion) {
+            if (entity.hasComponent(UIDockedTo) &&
+                entity.getValue(UIDockedTo, 'regionId') === homeRegion) {
+                return; // already home
+            }
+            if (entity.hasComponent(UIDockedTo)) {
+                entity.removeComponent(UIDockedTo);
+            }
+            entity.addComponent(UIDockedTo, { regionId: homeRegion });
+            return;
+        }
+        if (entity.hasComponent(UIDockedTo)) {
+            entity.removeComponent(UIDockedTo);
+        }
+        const homeDockMode = entity.getValue(UIWindowState, 'homeDockMode');
+        if (isDockMode(homeDockMode)) {
+            entity.setValue(UIWindow, 'dockMode', homeDockMode);
+        }
+        if (homeDockMode === DockMode.WorldLocked) {
+            const object = entity.object3D;
+            const home = entity.getVectorView(UIWindowState, 'homePosition');
+            if (object) {
+                object.position.set(home[0] ?? 0, home[1] ?? 0, home[2] ?? 0);
+                object.rotation.set(0, entity.getValue(UIWindowState, 'homeYaw'), 0);
+            }
+        }
+        // Follow modes re-snap on their own (the dock system syncs the Follower).
+    }
+    /** MIN when open, MAX when minimized - the label names the next action. */
+    syncMinimizeLabel(record) {
+        const entity = this.entitiesById.get(record.id);
+        const minimize = entity
+            ? this.documentOf(entity)?.getElementById(WINDOW_CHROME_IDS.minimize)
+            : undefined;
+        minimize?.setProperties({ text: minimizeLabelFor(record) });
+    }
+    syncPinLabel(record) {
+        const entity = this.entitiesById.get(record.id);
+        const pin = entity
+            ? this.documentOf(entity)?.getElementById(WINDOW_CHROME_IDS.pin)
+            : undefined;
+        pin?.setProperties({ text: pinLabelFor(record) });
+    }
+    releaseWindow(entity) {
+        const id = entity.getValue(UIWindow, 'windowId');
+        if (id && this.entitiesById.get(id) === entity) {
+            this.entitiesById.delete(id);
+            if (this.manager.has(id)) {
+                this.manager.close(id);
+            }
+        }
+    }
+    wireChrome(entity, id, title) {
+        const document = this.documentOf(entity);
+        if (!document) {
+            return;
+        }
+        // IWSDK 0.5 removed PanelUI.maxWidth/maxHeight; world size is now the
+        // document's own concern. Fit into the requested box, preserving aspect
+        // ratio. Zero means "leave intrinsic" so the entity transform owns scale.
+        const targetWidth = entity.getValue(UIWindow, 'targetWidth') ?? 0;
+        const targetHeight = entity.getValue(UIWindow, 'targetHeight') ?? 0;
+        if (targetWidth > 0 && targetHeight > 0) {
+            document.setTargetDimensions(targetWidth, targetHeight);
+        }
+        const element = (elementId) => document.getElementById(elementId);
+        const titleEl = element(WINDOW_CHROME_IDS.title);
+        if (titleEl && title) {
+            titleEl.setProperties({ text: title });
+        }
+        // Chrome buttons live on the drag surface - keep their presses out of
+        // the title-bar drag handle so clicks never turn into (or arm) drags.
+        const swallowPress = (button) => {
+            button?.addEventListener('pointerdown', (event) => {
+                event?.stopPropagation?.();
+            });
+        };
+        swallowPress(element(WINDOW_CHROME_IDS.pin));
+        swallowPress(element(WINDOW_CHROME_IDS.dock));
+        swallowPress(element(WINDOW_CHROME_IDS.minimize));
+        swallowPress(element(WINDOW_CHROME_IDS.close));
+        // Any press anywhere on the window brings it to the front.
+        const root = element(WINDOW_CHROME_IDS.window);
+        root?.addEventListener('pointerdown', () => {
+            if (this.manager.has(id)) {
+                this.manager.focus(id);
+            }
+        });
+        const close = element(WINDOW_CHROME_IDS.close);
+        if (close) {
+            if (entity.getValue(UIWindow, 'closable')) {
+                close.addEventListener('click', () => {
+                    // Destroying the entity disqualifies it everywhere; releaseWindow
+                    // then closes the manager record.
+                    entity.destroy();
+                });
+            }
+            else {
+                close.setProperties({ display: 'none' });
+            }
+        }
+        const minimize = element(WINDOW_CHROME_IDS.minimize);
+        if (minimize) {
+            if (entity.getValue(UIWindow, 'minimizable')) {
+                minimize.addEventListener('click', () => {
+                    if (this.manager.has(id)) {
+                        this.manager.toggleMinimized(id);
+                    }
+                });
+            }
+            else {
+                minimize.setProperties({ display: 'none' });
+            }
+        }
+        const pin = element(WINDOW_CHROME_IDS.pin);
+        if (pin) {
+            if (entity.getValue(UIWindow, 'pinnable')) {
+                pin.addEventListener('click', () => {
+                    if (this.manager.has(id)) {
+                        this.manager.togglePin(id);
+                    }
+                });
+            }
+            else {
+                pin.setProperties({ display: 'none' });
+            }
+        }
+        const dock = element(WINDOW_CHROME_IDS.dock);
+        dock?.addEventListener('click', () => this.returnHome(entity));
+    }
+    applyMinimized(id, minimized) {
+        const entity = this.entitiesById.get(id);
+        const document = entity ? this.documentOf(entity) : undefined;
+        const content = document?.getElementById(WINDOW_CHROME_IDS.content);
+        content?.setProperties({ display: minimized ? 'none' : 'flex' });
+    }
+    documentOf(entity) {
+        return PanelDocument.data.document[entity.index];
+    }
+}
+//# sourceMappingURL=window-system.js.map