add cursor docs

Author: nartc

apps/astro-docs/astro.config.mjs

@@ -132,6 +132,7 @@ export default defineConfig({
 							label: 'Advanced',
 							collapsed: true,
 							items: [
+								{ label: 'Directives', slug: 'core/advanced/directives' },
 								{ label: 'Portals', slug: 'core/advanced/portals' },
 								{ label: 'Routed Scene', slug: 'core/advanced/routed-scene' },
 								{ label: 'Performance', slug: 'core/advanced/performance' },

apps/astro-docs/src/components/cursor/cursor.ts

@@ -0,0 +1,85 @@
+import { DOCUMENT } from '@angular/common';
+import {
+	ChangeDetectionStrategy,
+	Component,
+	CUSTOM_ELEMENTS_SCHEMA,
+	Directive,
+	ElementRef,
+	inject,
+	signal,
+	viewChild,
+} from '@angular/core';
+import { extend, getLocalState, injectBeforeRender, injectObjectEvents, NgtCanvas } from 'angular-three';
+import { NgtsEnvironment } from 'angular-three-soba/staging';
+import * as THREE from 'three';
+import { type Mesh, Object3D } from 'three';
+
+extend(THREE);
+
+@Directive({ selector: '[cursor]', standalone: true })
+export class Cursor {
+	constructor() {
+		const elementRef = inject<ElementRef<Object3D>>(ElementRef);
+		const nativeElement = elementRef.nativeElement;
+
+		if (!nativeElement.isObject3D) return;
+
+		const localState = getLocalState(nativeElement);
+		if (!localState) return;
+
+		const document = inject(DOCUMENT);
+
+		injectObjectEvents(() => nativeElement, {
+			pointerover: () => {
+				document.body.style.cursor = 'pointer';
+			},
+			pointerout: () => {
+				document.body.style.cursor = 'default';
+			},
+		});
+	}
+}
+
+@Component({
+	standalone: true,
+	template: `
+		<ngt-spot-light [position]="[5, 5, 5]" [intensity]="Math.PI" [decay]="0" />
+		<ngt-point-light [position]="[-10, -10, -10]" [decay]="0" />
+
+		<ngt-mesh #mesh cursor (pointerover)="hovered.set(true)" (pointerout)="hovered.set(false)">
+			<ngt-box-geometry />
+			<ngt-mesh-standard-material [color]="hovered() ? 'mediumpurple' : 'maroon'" />
+		</ngt-mesh>
+	`,
+	schemas: [CUSTOM_ELEMENTS_SCHEMA],
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [Cursor, NgtsEnvironment],
+})
+export class SceneGraph {
+	hovered = signal(false);
+
+	meshRef = viewChild.required<ElementRef<Mesh>>('mesh');
+
+	constructor() {
+		injectBeforeRender(() => {
+			const mesh = this.meshRef().nativeElement;
+			mesh.rotation.x += 0.01;
+			mesh.rotation.y += 0.01;
+		});
+	}
+
+	protected readonly Math = Math;
+}
+
+@Component({
+	standalone: true,
+	template: `
+		<ngt-canvas [sceneGraph]="sceneGraph" [camera]="{ position: [0, 0, 2] }" />
+	`,
+	imports: [NgtCanvas],
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	host: { class: 'cursor-scene' },
+})
+export default class CursorScene {
+	sceneGraph = SceneGraph;
+}

apps/astro-docs/src/content/docs/core/advanced/directives.mdx

@@ -0,0 +1,65 @@
+---
+title: Extending Functionality with Directives
+description: Details about extending functionality with Directives
+---
+
+import CursorScene from '../../../../components/cursor/cursor';
+
+Angular Three elements are like regular DOM elements; they are just rendered to the Canvas instead of the DOM.
+With that in mind, we can extend the functionality of Angular Three elements by using Directives like we do with regular DOM elements.
+
+## Attribute Directives in Angular
+
+When we attach an **Attribute Directive** to an element, we have access to the element's host instance via `ElementRef` token. Angular Three elements
+return the actual THREE.js entity instance as the host instance so that we can access the THREE.js APIs to extend the functionality of the element.
+
+## Build a `cursor` Directive
+
+Let's build a `cursor` directive that will change the cursor to a `pointer` when the element is hovered.
+
+```angular-ts {'inject ElementRef<Object3D>': 4-5} {'Get localState': 9-10} {'Attach pointer events to host element': 14-15}
+@Directive({selector: '[cursor]', standalone: true})
+export class Cursor {
+  constructor() {
+
+		const elementRef = inject<ElementRef<Object3D>>(ElementRef);
+		const nativeElement = elementRef.nativeElement;
+
+		if (!nativeElement.isObject3D) return;
+
+		const localState = getLocalState(nativeElement);
+		if (!localState) return;
+
+		const document = inject(DOCUMENT);
+
+		injectObjectEvents(() => nativeElement, {
+			pointerover: () => {
+				document.body.style.cursor = 'pointer';
+			},
+			pointerout: () => {
+				document.body.style.cursor = 'default';
+			},
+		});
+  }
+}
+```
+
+Now, we can use the `cursor` directive on any element to change the cursor to a `pointer` when the element is hovered.
+
+:::note
+
+We do not constraint the type of the element that the `cursor` directive can be attached to but it only works for elements that
+are subjected to the events system like `Mesh` etc...
+
+:::
+
+```angular-html 'cursor'
+<ngt-mesh cursor (pointerover)="hovered.set(true)" (pointerout)="hovered.set(false)">
+	<ngt-box-geometry />
+	<ngt-mesh-standard-material [color]="hovered() ? 'mediumpurple' : 'maroon'" />
+</ngt-mesh>
+```
+
+<div class="h-96 w-full border border-dashed border-accent-500 rounded">
+	<CursorScene client:only />
+</div>

apps/astro-docs/src/content/docs/core/testing/advance.mdx

@@ -29,7 +29,6 @@ import { NgtTestBed } from 'angular-three/testing';
 describe('SceneGraph', () => {
 	it('should render', async () => {
 		const { scene, fireEvent, advance } = NgtTestBed.create(SceneGraph);
-    fireEvent.setAutoDetectChanges(true);
 
     expect(scene.children.length).toEqual(1);
     const mesh = scene.children[0] as Mesh;

apps/astro-docs/src/content/docs/core/testing/fire-event.mdx

@@ -25,17 +25,19 @@ fixture.detectChanges();
 
 #### `fireEvent.setAutoDetectChanges(auto: boolean)`
 
-After firing an event, we need to call `fixture.detectChanges()` to flush any changes that may have occurred (e.g: signal state changes).
+After firing an event, a Change Detection is needed with `fixture.detectChanges()` to flush any changes that may have occurred (e.g: signal state changes).
 
-We can use `fireEvent.setAutoDetectChanges(true)` to automatically call `fixture.detectChanges()` after firing an event.
-This toggles an internal flag whose life-cycle is tied to the scope of the test. If we want to disable auto-detection anytime, we can call `fireEvent.setAutoDetectChanges(false)`.
+`fireEvent` does this automatically, but we can disable it by calling `fireEvent.setAutoDetectChanges(false)`.
 
 ```ts
-const { fireEvent } = NgtTestBed.create(SceneGraph);
-fireEvent.setAutoDetectChanges(true);
+const { fixture, fireEvent } = NgtTestBed.create(SceneGraph);
+fireEvent.setAutoDetectChanges(false);
 
 await fireEvent(mesh, 'click');
+fixture.detectChanges();
+
 await fireEvent(mesh, 'pointerover');
+fixture.detectChanges();
 ```
 
 ## Example Scenario
@@ -49,7 +51,6 @@ import { NgtTestBed } from 'angular-three/testing';
 describe('SceneGraph', () => {
 	it('should render', async () => {
 		const { scene, fireEvent, advance } = NgtTestBed.create(SceneGraph);
-+    fireEvent.setAutoDetectChanges(true);
 
     expect(scene.children.length).toEqual(1);
     const mesh = scene.children[0] as Mesh;

libs/cannon/src/lib/physics.ts

@@ -183,6 +183,7 @@ export class NgtcPhysics {
 
 		this.autoEffect(() => {
 			const [worker, value] = [untracked(this.worker), computedValue()];
+			// @ts-expect-error
 			worker[key] = value;
 		});
 	}

libs/core/testing/src/lib/test-bed.ts

@@ -143,7 +143,7 @@ export class NgtTestBed {
 	}
 
 	static createEventFirer(store: NgtSignalStore<NgtState>, fixture: ComponentFixture<NgtTestCanvas>) {
-		let autoDetectChanges = false;
+		let autoDetectChanges = true;
 
 		async function fireEvent(el: NgtInstanceNode, eventName: keyof NgtEventHandlers, eventData: NgtAnyRecord = {}) {
 			const localState = getLocalState(el);

libs/core/testing/src/lib/test.spec.ts

@@ -60,7 +60,6 @@ describe('test canvas', () => {
 
 	it('should test', async () => {
 		const { scene, fireEvent, advance } = NgtTestBed.create(SceneGraph);
-		fireEvent.setAutoDetectChanges(true);
 
 		expect(scene.children.length).toEqual(2);