feat(soba): start migrating billboard and its story

Author: Chau Tran

libs/angular-three/src/lib/di/ref.ts

@@ -8,16 +8,17 @@ import {
     computed,
     inject,
     runInInjectionContext,
-    signal,
     untracked,
 } from '@angular/core';
 import { NgtInstanceNode } from '../types';
 import { getLocalState } from '../utils/instance';
 import { is } from '../utils/is';
 import { safeDetectChanges } from '../utils/safe-detect-changes';
+import { createSignal } from '../utils/signal';
 
 export type NgtInjectedRef<TElement> = ElementRef<TElement> & {
     children: (type?: 'objects' | 'nonObjects' | 'both') => Signal<NgtInstanceNode[]>;
+    untracked: TElement;
 };
 
 export function injectNgtRef<TElement>(
@@ -30,7 +31,7 @@ export function injectNgtRef<TElement>(
         const cdr = inject(ChangeDetectorRef);
 
         const ref = is.ref(initial) ? initial : new ElementRef<TElement>(initial as TElement);
-        const signalRef = signal(ref.nativeElement);
+        const signalRef = createSignal(ref.nativeElement);
         const readonlySignal = signalRef.asReadonly();
         const cached = new Map();
 
@@ -57,13 +58,21 @@ export function injectNgtRef<TElement>(
         Object.defineProperty(ref, 'nativeElement', {
             set: (newElement) => {
                 if (newElement !== untracked(signalRef)) {
-                    signalRef.set(newElement);
+                    try {
+                        signalRef.set(newElement);
+                    } catch {
+                        requestAnimationFrame(() => signalRef.set(newElement));
+                    }
                     safeDetectChanges(cdr);
                 }
             },
             get: () => readonlySignal(),
         });
 
-        return Object.assign(ref, { children });
+        Object.defineProperty(ref, 'untracked', {
+            get: () => untracked(readonlySignal),
+        });
+
+        return Object.assign(ref, { children }) as NgtInjectedRef<TElement>;
     });
 }

libs/angular-three/src/lib/renderer/renderer.ts

@@ -18,6 +18,7 @@ import { NgtStore } from '../stores/store';
 import type { NgtAnyRecord } from '../types';
 import { getLocalState, prepare } from '../utils/instance';
 import { is } from '../utils/is';
+import { createSignal } from '../utils/signal';
 import { NGT_COMPOUND_PREFIXES } from './di';
 import { NgtRendererClassId } from './enums';
 import { NgtRendererStore, type NgtRendererNode, type NgtRendererState } from './store';
@@ -112,7 +113,10 @@ export class NgtRenderer implements Renderer2 {
         if (name === SPECIAL_DOM_TAG.NGT_VALUE) {
             return this.store.createNode(
                 'three',
-                Object.assign({ __ngt_renderer__: { rawValue: undefined } }, { __ngt__: { isRaw: true } })
+                Object.assign(
+                    { __ngt_renderer__: { rawValue: undefined } },
+                    { __ngt__: { isRaw: true, parent: createSignal(null) } }
+                )
             );
         }
 

libs/angular-three/src/lib/renderer/utils.ts

@@ -74,7 +74,9 @@ export function attachThreeChild(parent: NgtInstanceNode, child: NgtInstanceNode
 
             // attach
             if (cLS.isRaw) {
-                cLS.parent.set(parent);
+                if (cLS.parent) {
+                    cLS.parent.set(parent);
+                }
                 // at this point we don't have rawValue yet, so we bail and wait until the Renderer recalls attach
                 if (child.__ngt_renderer__[NgtRendererClassId.rawValue] === undefined) return;
                 attach(parent, child.__ngt_renderer__[NgtRendererClassId.rawValue], attachProp);
@@ -91,7 +93,9 @@ export function attachThreeChild(parent: NgtInstanceNode, child: NgtInstanceNode
 
     pLS.add(child, added ? 'objects' : 'nonObjects');
 
-    cLS.parent.set(parent);
+    if (cLS.parent) {
+        cLS.parent.set(parent);
+    }
 
     if (cLS.afterAttach) cLS.afterAttach.emit({ parent, node: child });
 

libs/angular-three/src/lib/stores/signal.store.ts

@@ -3,13 +3,13 @@ import {
     Injectable,
     Optional,
     computed,
-    signal,
     untracked,
     type CreateComputedOptions,
     type Signal,
     type WritableSignal,
 } from '@angular/core';
 import type { NgtAnyRecord } from '../types';
+import { createSignal } from '../utils/signal';
 
 const STORE_COMPUTED_KEY = '__ngt_store_computed__' as const;
 
@@ -24,7 +24,7 @@ export class NgtSignalStore<TState extends object> {
         initialState: Partial<TState> = {} as unknown as Partial<TState>
     ) {
         initialState ??= {};
-        this.#state = signal(Object.assign(initialState, { __ngt_dummy_state__: Date.now() }) as TState);
+        this.#state = createSignal(Object.assign(initialState, { __ngt_dummy_state__: Date.now() }) as TState);
     }
 
     select<

libs/angular-three/src/lib/utils/instance.ts

@@ -1,5 +1,6 @@
-import { signal, untracked } from '@angular/core';
+import { untracked } from '@angular/core';
 import type { NgtAnyRecord, NgtInstanceLocalState, NgtInstanceNode } from '../types';
+import { createSignal } from './signal';
 import { checkUpdate } from './update';
 
 export function getLocalState<TInstance extends object = NgtAnyRecord>(
@@ -23,15 +24,15 @@ export function prepare<TInstance extends object = NgtAnyRecord>(
 
     if (localState?.primitive || !instance.__ngt__) {
         const {
-            objects = signal<NgtInstanceNode[]>([]),
-            nonObjects = signal<NgtInstanceNode[]>([]),
+            objects = createSignal<NgtInstanceNode[]>([]),
+            nonObjects = createSignal<NgtInstanceNode[]>([]),
             ...rest
         } = localState || {};
 
         instance.__ngt__ = {
             previousAttach: null,
             store: null,
-            parent: signal(null),
+            parent: createSignal(null),
             memoized: {},
             eventCount: 0,
             handlers: {},

libs/angular-three/src/lib/utils/signal.ts

@@ -0,0 +1,26 @@
+import { signal, type CreateSignalOptions, type WritableSignal } from '@angular/core';
+
+export function createSignal<TValue>(initialValue: TValue, options: CreateSignalOptions<TValue> = {}) {
+    const original = signal(initialValue, options);
+
+    const originalSet = original.set.bind(original);
+    const originalUpdate = original.update.bind(original);
+
+    original.set = (...args: Parameters<WritableSignal<TValue>['set']>) => {
+        try {
+            originalSet(...args);
+        } catch {
+            requestAnimationFrame(() => originalSet(...args));
+        }
+    };
+
+    original.update = (...args: Parameters<WritableSignal<TValue>['update']>) => {
+        try {
+            originalUpdate(...args);
+        } catch {
+            requestAnimationFrame(() => originalUpdate(...args));
+        }
+    };
+
+    return original;
+}

libs/soba/.storybook/main.js

@@ -1,3 +1,5 @@
+import { resolve } from 'path';
+
 const config = {
     stories: ['../**/*.stories.@(js|jsx|ts|tsx|mdx)'],
     addons: ['@storybook/addon-essentials'],

libs/soba/abstractions/README.md

@@ -0,0 +1,3 @@
+# angular-three-soba/abstractions
+
+Secondary entry point of `angular-three-soba`. It can be used by importing from `angular-three-soba/abstractions`.

libs/soba/abstractions/ng-package.json

@@ -0,0 +1,5 @@
+{
+    "lib": {
+        "entryFile": "src/index.ts"
+    }
+}

libs/soba/abstractions/src/billboard/billboard.ts

@@ -0,0 +1,64 @@
+import { CUSTOM_ELEMENTS_SCHEMA, Component, Input } from '@angular/core';
+import { NgtGroup, NgtSignalStore, extend, injectBeforeRender, injectNgtRef } from 'angular-three';
+import { Group } from 'three';
+
+extend({ Group });
+
+export type NgtsBillboardState = {
+    follow?: boolean;
+    lockX?: boolean;
+    lockY?: boolean;
+    lockZ?: boolean;
+};
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'ngts-billboard': NgtsBillboardState & NgtGroup;
+    }
+}
+
+@Component({
+    selector: 'ngts-billboard',
+    standalone: true,
+    template: `
+        <ngt-group ngtCompound [ref]="billboardRef">
+            <ng-content />
+        </ngt-group>
+    `,
+    schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class NgtsBillboard extends NgtSignalStore<NgtsBillboardState> {
+    @Input() billboardRef = injectNgtRef<Group>();
+
+    @Input() set follow(follow: boolean) {
+        this.set({ follow });
+    }
+    @Input() set lockX(lockX: boolean) {
+        this.set({ lockX });
+    }
+    @Input() set lockY(lockY: boolean) {
+        this.set({ lockY });
+    }
+    @Input() set lockZ(lockZ: boolean) {
+        this.set({ lockZ });
+    }
+
+    constructor() {
+        super({ follow: true, lockX: false, lockY: false, lockZ: false });
+        injectBeforeRender(({ camera }) => {
+            const ref = this.billboardRef.untracked;
+            const { follow, lockX, lockY, lockZ } = this.get();
+            if (!ref || !follow) return;
+            // save previous rotation in case we're locking an axis
+            const prevRotation = ref.rotation.clone();
+
+            // always face the camera
+            camera.getWorldQuaternion(ref.quaternion);
+
+            // re-adjust any axis that is locked
+            if (lockX) ref.rotation.x = prevRotation.x;
+            if (lockY) ref.rotation.y = prevRotation.y;
+            if (lockZ) ref.rotation.z = prevRotation.z;
+        });
+    }
+}