angular-three 2.0.0-beta.9 → 2.1.0

package/README.md

@@ -1,7 +1,224 @@
-# core
+# `angular-three`
 
-This library was generated with [Nx](https://nx.dev).
+A custom Renderer for Angular 18+ that uses Three.js to render 3D scenes.
 
-## Running unit tests
+## Compatibility
 
-Run `nx test core` to execute the unit tests.
+Angular Three v2 is still in beta and aims to be compatible with Angular 17+.
+
+## Installation
+
+```bash
+npm install angular-three@beta ngxtension three
+# yarn add angular-three@beta ngxtension three
+# pnpm add angular-three@beta ngxtension three
+```
+
+> Make sure to install `@types/three` as well
+
+## Usage
+
+```typescript
+import { extend } from 'angular-three';
+import { Mesh, BoxGeometry } from 'three';
+
+extend({
+	Mesh, // makes ngt-mesh available
+	BoxGeometry, // makes ngt-box-geometry available
+	/* ... */
+	MyMesh: Mesh, // makes ngt-my-mesh available
+});
+
+// alternatively for demo purposes, you can use the following
+// extend(THREE);
+// This includes the entire THREE.js namespace
+
+@Component({
+	// This Component is rendered in the Custom Renderer
+	standalone: true,
+	template: `
+		<ngt-mesh>
+			<ngt-box-geometry />
+		</ngt-mesh>
+	`,
+	schemas: [CUSTOM_ELEMENTS_SCHEMA], // required
+	changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class SceneGraph {}
+
+@Component({
+	// This Component is rendered normally in Angular.
+	selector: 'app-my-experience',
+	standalone: true,
+	template: `
+		<ngt-canvas [sceneGraph]="SceneGraph" />
+	`,
+	imports: [NgtCanvas],
+})
+export class MyExperience {
+	SceneGraph = SceneGraph;
+}
+```
+
+> The Component that renders `NgtCanvas` (`MyExperience` in this case) controls the dimensions of the canvas so make sure to style it accordingly.
+
+### Inputs
+
+- `sceneGraph: Type<any>`: **required**. This is the Component that renders your 3D Scene graph. It must be a standalone Component.
+- `gl?: NgtGLOptions`: This input allows you to configure the WebGL renderer used by Angular Three. You can provide a THREE.js renderer instance, properties for the default renderer, or a function that returns a renderer based on the canvas element.
+- `size?: NgtSize`: Specifies the dimensions of the renderer. If omitted, the component will automatically measure the canvas dimensions.
+- `shadows?: boolean | 'basic' | 'percentage' | 'soft' | 'variance' | Partial<WebGLShadowMap>`: Enables or disables shadows in the scene. You can provide a boolean value to toggle shadows on or off, or use specific strings to control the shadow type. Additionally, you can pass partial WebGLShadowMap options for fine-tuning.
+- `legacy?: boolean`: Disables three r139 color management when set to true.
+- `linear?: boolean`: Switches off automatic sRGB color space and gamma correction when set to true.
+- `flat?: boolean`: Uses THREE.NoToneMapping instead of THREE.ACESFilmicToneMapping when set to true.
+- `orthographic?: boolean`: Creates an orthographic camera instead of a perspective camera when set to true.
+- `frameloop?: 'always' | 'demand' | 'never'`: Controls the rendering mode. 'always' renders continuously, 'demand' renders only on state changes, and 'never' gives you manual control over rendering.
+- `performance?: Partial<Omit<NgtPerformance, 'regress'>>`: Allows you to configure performance options for adaptive performance.
+- `dpr?: NgtDpr`: Sets the target pixel ratio. You can provide a single number or a range [min, max].
+- `raycaster?: Partial<Raycaster>`: Configures the default raycaster used for interaction.
+- `scene?: Scene | Partial<Scene>`: Provides a THREE.js scene instance or properties to create a default scene.
+- `camera?: NgtCamera | Partial<NgtObject3DNode<Camera>>`: Provides a THREE.js camera instance or properties to create a default camera. You can also set the manual property to true to take control of the camera projection.
+- `events?: (store: NgtSignalStore<NgtState>) => NgtEventManager<HTMLElement>`: Allows you to customize the event manager for handling pointer events.
+- `eventSource?: HTMLElement | ElementRef<HTMLElement>`: Specifies the target element where events are subscribed. By default, it's the div wrapping the canvas.
+- `eventPrefix?: 'offset' | 'client' | 'page' | 'layer' | 'screen'`: Sets the event prefix used for canvas pointer events.
+- `lookAt?: Vector3 | Parameters<Vector3['set']>`: Defines the default coordinate for the camera to look at.
+
+### Outputs
+
+- `created`: Emitted when the canvas is created.
+- `pointerMissed`: Emitted when a pointer event is not captured by any element (aka clicking on the canvas)
+
+## Intellisense support
+
+Since Angular Three is a custom Renderer, the elements are not recognized by the Angular Language Service.
+
+### Jetbrains IDE
+
+The consumers can add `web-types` property to the workspace's `package.json` and set the value to `node_modules/angular-three/web-types.json`.
+
+```json
+{
+	"web-types": "node_modules/angular-three/web-types.json"
+}
+```
+
+### VSCode
+
+Similarly, there's `node_modules/angular-three/metadata.json` file that can be used to provide intellisense support for VSCode users.
+
+The consumers can enable it via `html.customData` in their `settings.json` file.
+
+```json
+{
+	"html.customData": ["node_modules/angular-three/metadata.json"]
+}
+```
+
+## Input Bindings
+
+Input bindings for `ngt-*` elements work the same way as they do in Angular.
+
+> You can consult THREE.js documentation on what is available on the entities
+
+```html
+<ngt-mesh [position]="[x, y, z]" [rotation]="[x, y, z]">
+	<ngt-mesh-basic-material color="hotpink" />
+</ngt-mesh>
+```
+
+## Events
+
+Angular Three Custom Renderer supports the following events on applicable objects (`ngt-mesh`, `ngt-group` etc...)
+
+```
+'click',
+'contextmenu',
+'dblclick',
+'pointerup',
+'pointerdown',
+'pointerover',
+'pointerout',
+'pointerenter',
+'pointerleave',
+'pointermove',
+'pointermissed',
+'pointercancel',
+'wheel',
+```
+
+In addition, there are 2 special events that the consumers can listen to;
+
+- `attached`: when the element is attached to its parent
+- `updated`: when the element properties are updated
+
+## Constructor Arguments
+
+In THREE.js, there are some entities that require the consumers to dispose and recreate them if their parameters change; like the Geometries.
+
+To handle this, Angular Three exports a `NgtArgs` structural directive that always accepts an Array of values. The consumers can consult THREE.js documentations to know what values are applicable for what entities and their order.
+
+```html
+<!-- for example, new BoxGeometry(width, height, depth) -->
+<ngt-box-geometry *args="[width, height, depth]" />
+```
+
+`NgtArgs`, as a structural directive, ensures to create a new instance of the entity when the value changes
+
+## Parameters
+
+Beside the normal properties that `ngt-*` elements can accept for Input bindings, the consumers can also pass a `parameters` object to a special property `[parameters]` on the elements. This parameters object will be used to apply the properties on the entity.
+
+```html
+<!-- instead of <ngt-mesh [position]="[x, y, z]" [scale]="scale" /> -->
+<ngt-mesh [parameters]="{ position: [x, y, z], scale }" />
+```
+
+## Element Queries
+
+The consumers can query for the THREE.js entities like they would do in normal HTML Angular Template.
+
+```ts
+@Component({
+	template: `
+		<ngt-mesh #mesh></ngt-mesh>
+	`,
+})
+export class Box {
+	mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+	//  notice that it is an ElementRef of THREE.Mesh instead of an HTMLElement
+}
+```
+
+## Animation Loop
+
+In order to participate in the animation loop, use `injectBeforeRender` inject function
+
+```ts
+@Component({
+	/*...*/
+})
+export class Box {
+	mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+
+	constructor() {
+		injectBeforeRender(() => {
+			// runs every frame
+			const mesh = this.mesh().nativeElement;
+			mesh.rotation.x += 0.01;
+		});
+	}
+}
+```
+
+## Store
+
+Angular Three keeps track of its state via an internal store. The consumers can access this store via the `injectStore` inject function
+
+```ts
+export class Box {
+	store = injectStore();
+	viewport = this.store.select('viewport'); // Signal<NgtViewport>
+	camera = this.store.select('camera'); // Signal<NgtCamera> - the default camera
+	/* many more properties */
+}
+```

package/esm2022/index.mjs

@@ -1,26 +1,25 @@
-export * from './lib/before-render';
 export * from './lib/canvas';
 export * from './lib/directives/args';
-export * from './lib/directives/key';
-export * from './lib/directives/parent';
-export * from './lib/directives/repeat';
+export * from './lib/directives/selection';
+export * from './lib/html';
 export * from './lib/instance';
 export * from './lib/loader';
-export { addAfterEffect, addEffect, addTail } from './lib/loop';
-export { NgtPortal, NgtPortalContent } from './lib/portal';
-export * from './lib/ref';
+export * from './lib/loop';
+export * from './lib/pipes/hexify';
+export * from './lib/portal';
 export * from './lib/renderer';
+export * from './lib/roots';
 export * from './lib/routed-scene';
 export * from './lib/store';
-export * from './lib/three-types';
-export * from './lib/types';
 export * from './lib/utils/apply-props';
-export * from './lib/utils/assert-injection-context';
-export { createAttachFunction } from './lib/utils/attach';
-export * from './lib/utils/create-injection-token';
+export * from './lib/utils/attach';
+export * from './lib/utils/before-render';
 export * from './lib/utils/is';
 export * from './lib/utils/make';
-export * from './lib/utils/safe-detect-changes';
+export * from './lib/utils/non-nullish';
+export * from './lib/utils/object-events';
+export * from './lib/utils/parameters';
+export * from './lib/utils/resolve-ref';
 export * from './lib/utils/signal-store';
 export * from './lib/utils/update';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9saWJzL2NvcmUvc3JjL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyx5QkFBeUIsQ0FBQztBQUV4QyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsY0FBYyxDQUFDO0FBQzdCLE9BQU8sRUFBRSxjQUFjLEVBQUUsU0FBUyxFQUFFLE9BQU8sRUFBRSxNQUFNLFlBQVksQ0FBQztBQUNoRSxPQUFPLEVBQUUsU0FBUyxFQUFFLGdCQUFnQixFQUFFLE1BQU0sY0FBYyxDQUFDO0FBQzNELGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxzQ0FBc0MsQ0FBQztBQUNyRCxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxvQkFBb0IsQ0FBQztBQUMxRCxjQUFjLG9DQUFvQyxDQUFDO0FBQ25ELGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGlDQUFpQyxDQUFDO0FBQ2hELGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxvQkFBb0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCAqIGZyb20gJy4vbGliL2JlZm9yZS1yZW5kZXInO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvY2FudmFzJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL2RpcmVjdGl2ZXMvYXJncyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9kaXJlY3RpdmVzL2tleSc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9kaXJlY3RpdmVzL3BhcmVudCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9kaXJlY3RpdmVzL3JlcGVhdCc7XG5leHBvcnQgeyB0eXBlIE5ndENhbWVyYSwgdHlwZSBOZ3RUaHJlZUV2ZW50IH0gZnJvbSAnLi9saWIvZXZlbnRzJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL2luc3RhbmNlJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL2xvYWRlcic7XG5leHBvcnQgeyBhZGRBZnRlckVmZmVjdCwgYWRkRWZmZWN0LCBhZGRUYWlsIH0gZnJvbSAnLi9saWIvbG9vcCc7XG5leHBvcnQgeyBOZ3RQb3J0YWwsIE5ndFBvcnRhbENvbnRlbnQgfSBmcm9tICcuL2xpYi9wb3J0YWwnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvcmVmJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3JlbmRlcmVyJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3JvdXRlZC1zY2VuZSc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9zdG9yZSc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi90aHJlZS10eXBlcyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi90eXBlcyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9hcHBseS1wcm9wcyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9hc3NlcnQtaW5qZWN0aW9uLWNvbnRleHQnO1xuZXhwb3J0IHsgY3JlYXRlQXR0YWNoRnVuY3Rpb24gfSBmcm9tICcuL2xpYi91dGlscy9hdHRhY2gnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvdXRpbHMvY3JlYXRlLWluamVjdGlvbi10b2tlbic7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9pcyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9tYWtlJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3V0aWxzL3NhZmUtZGV0ZWN0LWNoYW5nZXMnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvdXRpbHMvc2lnbmFsLXN0b3JlJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3V0aWxzL3VwZGF0ZSc7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9saWJzL2NvcmUvc3JjL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLDJCQUEyQixDQUFDO0FBQzFDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsMkJBQTJCLENBQUM7QUFDMUMsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYyxvQkFBb0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCAqIGZyb20gJy4vbGliL2NhbnZhcyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9kaXJlY3RpdmVzL2FyZ3MnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvZGlyZWN0aXZlcy9zZWxlY3Rpb24nO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvaHRtbCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9pbnN0YW5jZSc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9sb2FkZXInO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvbG9vcCc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9waXBlcy9oZXhpZnknO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvcG9ydGFsJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3JlbmRlcmVyJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3Jvb3RzJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3JvdXRlZC1zY2VuZSc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi9zdG9yZSc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9hcHBseS1wcm9wcyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9hdHRhY2gnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvdXRpbHMvYmVmb3JlLXJlbmRlcic7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9pcyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9tYWtlJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3V0aWxzL25vbi1udWxsaXNoJztcbmV4cG9ydCAqIGZyb20gJy4vbGliL3V0aWxzL29iamVjdC1ldmVudHMnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvdXRpbHMvcGFyYW1ldGVycyc7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9yZXNvbHZlLXJlZic7XG5leHBvcnQgKiBmcm9tICcuL2xpYi91dGlscy9zaWduYWwtc3RvcmUnO1xuZXhwb3J0ICogZnJvbSAnLi9saWIvdXRpbHMvdXBkYXRlJztcblxuZXhwb3J0IHR5cGUgKiBmcm9tICcuL2xpYi90aHJlZS10eXBlcyc7XG5leHBvcnQgdHlwZSAqIGZyb20gJy4vbGliL3R5cGVzJztcbiJdfQ==