diff --git a/apps/astro-docs/astro.config.mjs b/apps/astro-docs/astro.config.mjs
index ca3b0414..b072ec41 100644
--- a/apps/astro-docs/astro.config.mjs
+++ b/apps/astro-docs/astro.config.mjs
@@ -2,7 +2,8 @@ import analogjsangular from '@analogjs/astro-angular';
import starlight from '@astrojs/starlight';
import tailwind from '@astrojs/tailwind';
import { defineConfig } from 'astro/config';
-import { readFileSync } from 'fs';
+import { readFileSync } from 'node:fs';
+import starlightBlog from 'starlight-blog';
function includeContentPlugin() {
const map = new Map();
@@ -71,6 +72,17 @@ export default defineConfig({
}),
starlight({
title: 'Angular Three',
+ plugins: [
+ starlightBlog({
+ authors: {
+ chau: {
+ name: 'Chau Tran',
+ url: 'https://nartc.me',
+ picture: 'https://avatars.githubusercontent.com/u/25516557?v=4',
+ },
+ },
+ }),
+ ],
favicon: './src/assets/angular-three-dark.svg',
tableOfContents: {
minHeadingLevel: 2,
diff --git a/apps/astro-docs/package.json b/apps/astro-docs/package.json
index fdaf2504..73b2326c 100644
--- a/apps/astro-docs/package.json
+++ b/apps/astro-docs/package.json
@@ -12,15 +12,16 @@
"dependencies": {
"@analogjs/astro-angular": "^1.6.4-beta.1",
"@astrojs/check": "^0.9.3",
- "@astrojs/mdx": "^3.1.3",
- "@astrojs/starlight": "^0.26.1",
+ "@astrojs/mdx": "^3.1.5",
+ "@astrojs/starlight": "^0.26.2",
"@astrojs/tailwind": "^5.1.0",
"angular-three": "^2.0.0-beta.314",
"angular-three-cannon": "^2.0.0-beta.314",
"angular-three-postprocessing": "^2.0.0-beta.314",
"angular-three-soba": "^2.0.0-beta.314",
- "astro": "^4.14.2",
+ "astro": "^4.15.2",
"sharp": "^0.32.5",
+ "starlight-blog": "^0.12.0",
"tailwindcss": "^3.4.6"
},
"nx": {},
diff --git a/apps/astro-docs/src/components/hud/hud.ts b/apps/astro-docs/src/components/hud/hud.ts
new file mode 100644
index 00000000..715bd119
--- /dev/null
+++ b/apps/astro-docs/src/components/hud/hud.ts
@@ -0,0 +1,197 @@
+import {
+ CUSTOM_ELEMENTS_SCHEMA,
+ ChangeDetectionStrategy,
+ Component,
+ ElementRef,
+ computed,
+ inject,
+ input,
+ signal,
+ viewChild,
+} from '@angular/core';
+import {
+ NgtArgs,
+ NgtCanvas,
+ NgtPortal,
+ NgtPortalContent,
+ extend,
+ injectBeforeRender,
+ injectStore,
+} from 'angular-three';
+import { NgtsText } from 'angular-three-soba/abstractions';
+import { NgtsOrthographicCamera, NgtsPerspectiveCamera } from 'angular-three-soba/cameras';
+import { NgtsOrbitControls } from 'angular-three-soba/controls';
+import { NgtsEnvironment, NgtsRenderTexture, NgtsRenderTextureContent } from 'angular-three-soba/staging';
+import * as THREE from 'three';
+import { Matrix4, Mesh, Scene } from 'three';
+
+extend(THREE);
+
+@Component({
+ selector: 'app-torus',
+ standalone: true,
+ template: `
+
+
+
+
+ `,
+ imports: [NgtArgs],
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Torus {
+ scale = input(1);
+ hovered = signal(false);
+ color = computed(() => (this.hovered() ? 'hotpink' : 'orange'));
+}
+
+@Component({
+ selector: 'app-face-material',
+ standalone: true,
+ template: `
+
+
+
+
+
+
+
+
+
+ `,
+ imports: [NgtsText, NgtsRenderTexture, NgtsOrthographicCamera, NgtArgs, NgtsRenderTextureContent],
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class FaceMaterial {
+ index = input.required();
+ text = input.required();
+
+ box = inject(Box);
+
+ color = computed(() => (this.box.hovered() === this.index() ? 'hotpink' : 'orange'));
+}
+
+@Component({
+ selector: 'app-box',
+ standalone: true,
+ template: `
+
+
+ @for (face of faces; track face) {
+
+ }
+
+ `,
+ imports: [FaceMaterial],
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Box {
+ position = input([0, 0, 0]);
+
+ mesh = viewChild.required>('mesh');
+
+ hovered = signal(-1);
+ clicked = signal(false);
+
+ scale = computed(() => (this.clicked() ? 1.5 : 1));
+
+ faces = ['front', 'back', 'top', 'bottom', 'left', 'right'];
+}
+
+@Component({
+ selector: 'app-view-cube',
+ standalone: true,
+ template: `
+
+
+
+
+
+
+
+
+
+
+
+ `,
+ imports: [Box, NgtPortal, NgtPortalContent, NgtsPerspectiveCamera],
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ViewCube {
+ protected readonly Math = Math;
+
+ private store = injectStore();
+ private camera = this.store.select('camera');
+ private viewport = this.store.select('viewport');
+
+ box = viewChild(Box);
+
+ boxPosition = computed(() => [this.viewport().width / 2 - 1, this.viewport().height / 2 - 1, 0]);
+
+ scene = computed(() => {
+ const scene = new Scene();
+ scene.name = 'hud-view-cube-virtual-scene';
+ return scene;
+ });
+
+ constructor() {
+ const matrix = new Matrix4();
+ injectBeforeRender(() => {
+ const box = this.box()?.mesh().nativeElement;
+ if (box) {
+ matrix.copy(this.camera().matrix).invert();
+ box.quaternion.setFromRotationMatrix(matrix);
+ }
+ });
+ }
+}
+
+@Component({
+ standalone: true,
+ template: `
+
+
+
+
+
+
+
+
+ `,
+ imports: [NgtsOrbitControls, NgtsEnvironment, Torus, ViewCube, NgtArgs],
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+ host: { class: 'hud-experience' },
+})
+export class Experience {
+ protected readonly Math = Math;
+}
+
+@Component({
+ standalone: true,
+ template: `
+
+ `,
+ imports: [NgtCanvas],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+ host: { class: 'hud-docs' },
+})
+export default class HudScene {
+ scene = Experience;
+}
diff --git a/apps/astro-docs/src/components/lightformer/lightformer.ts b/apps/astro-docs/src/components/lightformer/lightformer.ts
new file mode 100644
index 00000000..315660c6
--- /dev/null
+++ b/apps/astro-docs/src/components/lightformer/lightformer.ts
@@ -0,0 +1,69 @@
+import { ChangeDetectionStrategy, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, viewChild } from '@angular/core';
+import { extend, injectBeforeRender, NgtArgs, NgtCanvas } from 'angular-three';
+import { NgtsOrbitControls } from 'angular-three-soba/controls';
+import { NgtsContactShadows, NgtsEnvironment, NgtsLightformer } from 'angular-three-soba/staging';
+import * as THREE from 'three';
+import { Mesh } from 'three';
+
+extend(THREE);
+
+@Component({
+ standalone: true,
+ template: `
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ `,
+ imports: [NgtsEnvironment, NgtsLightformer, NgtsContactShadows, NgtArgs, NgtsOrbitControls],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class Experience {
+ protected readonly Math = Math;
+
+ private cube = viewChild.required>('cube');
+
+ constructor() {
+ injectBeforeRender(({ delta }) => {
+ const cube = this.cube().nativeElement;
+ cube.rotation.y += delta * 0.2;
+ });
+ }
+}
+
+@Component({
+ standalone: true,
+ template: `
+
+ `,
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+ imports: [NgtCanvas],
+})
+export default class LightformerScene {
+ scene = Experience;
+}
diff --git a/apps/astro-docs/src/content/config.ts b/apps/astro-docs/src/content/config.ts
index f31a3be9..176fe874 100644
--- a/apps/astro-docs/src/content/config.ts
+++ b/apps/astro-docs/src/content/config.ts
@@ -1,6 +1,9 @@
import { docsSchema } from '@astrojs/starlight/schema';
import { defineCollection } from 'astro:content';
+import { blogSchema } from 'starlight-blog/schema';
export const collections = {
- docs: defineCollection({ schema: docsSchema() }),
+ docs: defineCollection({
+ schema: docsSchema({ extend: (context) => blogSchema(context) }),
+ }),
};
diff --git a/apps/astro-docs/src/content/docs/blog/v2.mdx b/apps/astro-docs/src/content/docs/blog/v2.mdx
new file mode 100644
index 00000000..1b5aaf4a
--- /dev/null
+++ b/apps/astro-docs/src/content/docs/blog/v2.mdx
@@ -0,0 +1,412 @@
+---
+title: Angular Three v2 is here! ❤️
+excerpt: Angular Three v2 is here! ❤️
+date: 2024-09-02
+authors:
+ - chau
+tags:
+ - angular
+ - three
+ - release
+featured: true
+---
+import { Tabs, TabItem, Code } from '@astrojs/starlight/components';
+import HudScene, {content as hudContent} from '../../../components/hud/hud?includeContent';
+import LightformerScene, {content as lightformerContent} from '../../../components/lightformer/lightformer?includeContent';
+
+
+After almost a year of development, we're thrilled to announce the release of Angular Three v2! 🎉 Through countless examples and tutorials from other [THREE.js](https://threejs.org) ecosystems, we've identified the shortcomings of the previous version of Angular Three. Since then, we've been working tirelessly to enhance the library, making it more stable, performant, and predictable when working with THREE.js scene graphs.
+
+Following over 100 beta releases, we're confident that Angular Three v2 is ready for production and represents a significant improvement for the Angular THREE.js ecosystem as a whole.
+
+## Foreword
+
+Angular Three v2 is a major release with a substantial time gap since the previous version. It aims to address the limitations of the first version, resulting in numerous breaking changes. Some of these changes are subtle and may not be immediately apparent.
+
+Consequently, even though the surface-level APIs of v1 and v2 are similar, as both use a custom renderer, we're not providing an upgrade path from v1 to v2. Additionally, Angular Three v2 requires a minimum of Angular v18. Therefore, Angular Three v2 is better suited for new projects rather than upgrading existing ones.
+
+## What's new in Angular Three v2
+
+- Angular Signals 🚦
+- Improved performance and stability 📈
+- Better composability 🧩
+- Better `Portal` powered components 🪞
+- Improved documentation 📖
+
+While this list might seem modest at first glance, the core improvements in Angular Three v2 unlock a wealth of potential that has been incorporated into other packages like `angular-three-soba`, `angular-three-cannon`, and `angular-three-postprocessing`.
+
+### Angular Signals 🚦
+
+The most significant change in Angular Three v2 is the adoption of [Angular Signals](https://angular.dev/guide/signals). Angular Signals is a powerful and flexible way to manage state in modern Angular applications. Angular Signals also provides an entire set of new tools: Signal Inputs, Signal Outputs, and Signal Queries; all of which are designed to work seamlessly together.
+
+Angular Three v2's core is built on Angular Signals. This means that most, if not all, of Angular Three v2's APIs are Signals-based: they can accept Signals or Functions as arguments and return Signals as results.
+
+Let's examine some examples from across the Angular Three ecosystem.
+
+#### `injectStore`
+
+`injectStore` is a [Custom Inject Function (CIF)](https://nartc.me/blog/inject-function-the-right-way/) that allows the consumers to interact with the Angular Three Store. The store contains THREE.js building blocks such as the root `Scene`, the default `Camera`, and the `Renderer` itself etc...
+
+```angular-ts {'1. Get the NgtStore instance': 14-15} {'2. select() to access the Signals': 17-19} {'3. Use the signals in the template': 7-8}
+@Component({
+ template: `
+
+
+
+
+
+
+ `,
+ imports: [NgtArgs]
+})
+export class MyCmp {
+
+
+ private store = injectStore();
+
+
+ protected camera = this.store.select('camera'); // Signal
+ protected domElement = this.store.select('gl', 'domElement'); // Signal
+}
+```
+
+#### `injectLoader`
+
+`injectLoader` is a [Custom Inject Function (CIF)](https://nartc.me/blog/inject-function-the-right-way/) that allows the consumers to interact with THREE.js loaders.
+
+```angular-ts {'Signal Input in action': 12-13} {'Integrating seamlessly with Signals': 15-16}
+@Component({
+ template: `
+ @if (gltf(); as gltf) {
+
+ }
+ `,
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ imports: [NgtArgs]
+})
+export class MyModel {
+
+
+ path = input.required();
+
+
+ gltf = injectLoader(() => GLTFLoader, this.path);
+}
+```
+
+#### `injectBody` (from `angular-three-cannon`)
+
+`injectBody` is a [Custom Inject Function (CIF)](https://nartc.me/blog/inject-function-the-right-way/) that allows the consumers to interact with Cannon.js bodies.
+
+```angular-ts {'Signal Queries in action': 14-15} {'Integrating seamlessly with Signals': 17-21} {'Using Signals result to control the physics body': 29-31}
+@Component({
+ template: `
+
+
+
+
+ `,
+ schemas: [CUSTOM_ELEMENTS_SCHEMA],
+ changeDetection: ChangeDetectionStrategy.OnPush,
+ imports: [NgtArgs],
+})
+export class Box {
+
+
+ meshRef = viewChild.required>('mesh');
+
+
+ boxApi = injectBox(
+ () => ({ args: [4, 4, 4], mass: 1, type: 'Kinematic' }),
+ this.meshRef
+ );
+
+ constructor() {
+ injectBeforeRender(({ clock }) => {
+ const api = this.boxApi();
+ if (!api) return;
+ const t = clock.getElapsedTime();
+
+
+ api.position.set(Math.sin(t * 2) * 5, Math.cos(t * 2) * 5, 3);
+ api.rotation.set(Math.sin(t * 6), Math.cos(t * 6), 0);
+ });
+ }
+}
+```
+
+These examples demonstrate just a few of the Angular Signals integrations. By leveraging Angular Signals, Angular Three v2 has eliminated much of its internal artificial timing and complexity in coordinating different 3D entities. This, in turn, makes Angular Three v2 more performant, stable, and predictable.
+
+### Improved performance and stability 📈
+
+While Angular Three has always been performant, thanks to Angular, the introduction of Angular Signals has allowed Angular Three v2 to significantly improve its stability story, with performance benefiting as well.
+
+#### Elimination of custom `NgtRef`
+
+Before Angular Signals, Angular Three used a custom `NgtRef` to track the life-cycle of THREE.js entities on the template via the `[ref]` custom property binding.
+
+
+```angular-ts
+@Component({
+ template: `
+
+ `
+})
+export class MyCmp {
+ meshRef = injectNgtRef();
+}
+```
+
+The primary purpose of NgtRef was to provide reactivity to `ElementRef`. With Signal Queries, this is no longer necessary. Instead, Angular Three v2 embraces Angular's approach using its query APIs like `viewChild`, `viewChildren`, `contentChild`, and `contentChildren`.
+
+```diff lang="angular-ts"
+@Component({
+ template: `
+-
++
+ `
+})
+export class MyCmp {
+- meshRef = injectNgtRef();
++ meshRef = viewChild.required>('mesh'); // Signal>
+}
+```
+
+This change reduces the amount of Angular Three internals needed to handle the custom `NgtRef`. The timing of when Signal Queries are resolved is controlled by Angular, and it should be more streamlined and predictable to end users.
+
+#### Change Detection and Events
+
+Previously, Angular Three relied on `ChangeDetectorRef` to trigger change detections on events like `pointerover`, `click`, etc. This was necessary because Angular Three has always run outside Angular Zone, and to provide a better experience for end users, we had to make the event system work as seamlessly as possible. Passing around the `ChangeDetectorRef` and ensuring that the correct Component instance was a significant challenge and was never entirely reliable.
+
+With Angular v18, Signals and `OnPush` change detection strategy have been designed to work well together. This means that end users can use Signal to drive the state of their components, and Angular Three events will be automatically handled by Angular internal change detection mechanism.
+
+```angular-ts
+@Component({
+ template: `
+
+
+
+
+ `,
+ changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class MyCmp {
+ protected hovered = signal(false);
+ protected active = signal(false);
+
+ protected scale = computed(() => this.active() ? 1.5 : 1);
+ protected color = computed(() => (this.hovered() ? 'hotpink' : 'orange'));
+}
+```
+
+:::tip[Did you know?]
+
+If you are feeling good about Zoneless, you can even enable it with `withExperimentalZonelessChangeDetection` and everything will still work as expected as long as you use Signals to drive the state of your applications.
+
+```ts
+bootstrapApplication(AppComponent, {
+ providers: [
+ provideExperimentalZonelessChangeDetection()
+ ]
+});
+```
+
+:::
+
+These examples are just a few of the many stability improvements that Angular Three v2 has introduced. There are numerous additional "under the hood" enhancements that unlock many more features and possibilities, which we'll explore in the following sections.
+
+### Better composability 🧩
+
+Angular Three v2 overhauls the `NgtRenderer` to make it more composable. `NgtRenderer` now embraces Angular's default content projection
+mechanism to provide a more flexible, predictable, and performant way to render content. In turns, this makes composing different THREE.js entities much easier and more straightforward.
+
+This improvement was inspired by a new addition to Angular Content Projection: Default content. This new feature allows Angular Three to provide default contents for some abstractions like `NgtsLightformer` while still allowing consumers to override it.
+
+Consider the following example:
+
+```angular-ts
+@Component({
+ template: `
+
+
+
+
+
+
+
+ `
+})
+export class Box {}
+```
+
+In this snippet, we have a `Box` component that renders a `Mesh` with `BoxGeometry` and a **default** `MeshNormalMaterial`. The `Box` component can be used as follows:
+
+```angular-html
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### Object Inputs
+
+Another win for composability is unlocked by Signal Inputs. With Signal Inputs, Angular Three v2 makes uses of [Object Inputs](https://nartc.me/blog/angular-object-inputs/) to provide a more composable way to pass inputs into custom components via `[parameters]` custom property binding.
+
+Let's revisit the Box component and allow consumers to pass in everything they can pass into Box to control the Mesh and the geometry.
+
+```angular-ts
+import { NgtMesh } from 'angular-three';
+
+@Component({
+ template: `
+
+
+
+
+
+
+
+ `,
+ imports: [NgtArgs]
+})
+export class Box {
+ boxArgs = input>([1, 1, 1]);
+ options = input>({});
+}
+```
+
+Now the consumers can use `Box` component as follows:
+
+```angular-html
+
+
+
+
+
+
+```
+
+All `angular-three-soba` components are built on top of Object Inputs concept, which allows for a much better composability story without the need to implement custom `ngtCompound` construct in the renderer internals.
+
+Thanks to this new improvement, abstractions in `angular-three-soba` are significantly easier to use and reason about. Here's another example of `Text3D` component with `Center` and `Float`.
+
+```angular-html {'center things': 3-4 } {'float things': 6-7 } {'text 3d': 9-10 } { 'content projection for text material': 16-17 }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+You just use them, nest them, and compose them. The possibilities are endless.
+
+### Better `Portal` powered components 🪞
+
+`NgtPortal` has also received a major upgrade. It is now truly a portal with a separate layered `NgtStore` on top of the default root `NgtStore`. This means that the content of `NgtPortal` is rendered into an off-screen buffer, with access to the state of both the root and the layered `NgtStore`. This allows consumers to have better predictability and control over the components rendered inside an `ngt-portal` component.
+
+#### Heads-up display example
+
+For instance, we can use `NgtPortal` and `NgtsRenderTexture` (which also relies on `NgtPortal`) to create a heads-up display (HUD) sample.
+
+The main scene contains the torus (donut). The view cube (HUD) is rendered in a portal with its own `PerspectiveCamera`. Then each face of the view cube is yet rendered into a separate portal with its own `OrthographicCamera` and a `Text` component to render the face name.
+
+You can check out the code here: [HudScene](https://github.com/angular-threejs/angular-three/blob/main/apps/kitchen-sink/src/app/soba/hud/experience.ts)
+
+
+
+
+
+
+
+
+
+
+
+
+
+