docs: finish current API

Author: nartc

apps/documentation/docs/api/additional-exports.mdx

@@ -0,0 +1,36 @@
+---
+id: additional-exports
+title: Additional Exports
+sidebar_label: Additional Exports
+---
+
+## `injectBeforeRender()`
+
+A shortcut to register a before render callback
+
+```ts
+@Component({
+    /*...*/
+})
+export class SceneGraph {
+    readonly sub = injectBeforeRender(() => {}, 0);
+}
+```
+
+:::info
+
+`injectBeforeRender()` automatically cleans up the before render but it returns the reference to the clean up function.
+We can call this function anytime to clean up the before render, not just in `ngOnDestroy`
+
+:::
+
+## `is`
+
+A collection of utility functions to assert object type
+
+```ts
+is.obj(a); // checks if a value is an object; not an Array nor a Function
+is.ref(a); // checks if a value is ElementRef
+is.object3D(a); // checks if a value is an instance of THREE.Object3D
+// and more
+```

apps/documentation/docs/api/custom-renderer.mdx

@@ -239,7 +239,7 @@ See [TBD: ngt-value](#)
 
 ### `ref`
 
-See [TBD: ref](#)
+See [Ref](./ref)
 
 ## Outputs
 

apps/documentation/docs/api/directives/args.mdx

@@ -0,0 +1,47 @@
+---
+id: args
+title: NgtArgs
+sidebar_label: NgtArgs
+---
+
+Some THREE.js entities like Geometries accept **Constructor Arguments** and it is **required** to reconstruct
+these entities when the arguments change.
+
+```ts
+let geometry = new BoxGeometry(); // [1, 1, 1] box
+mesh.geometry = geometry;
+
+// later when we want a bigger box
+mesh.geometry.dispose(); // dispose old box
+// construct new box
+geometry = new BoxGeometry(2, 2, 2); // [2, 2, 2] box
+mesh.geometry = geometry;
+```
+
+To achieve this with the Custom Renderer, NGT provides a structural directive `NgtArgs`
+
+```html
+<ngt-box-geometry *args="boxArgs" />
+```
+
+When `boxArgs` changes, `*args` will destroy the current instance of `ngt-box-geometry` then re-create a new one with
+the new `boxArgs`
+
+`*args` accepts an Array of **Constructor Arguments** that the underlying object accepts.
+
+```html
+<ngt-box-geometry *args="[width, height, depth, widthSegments, heightSegments, depthSegments]" />
+
+<ngt-instanced-mesh *args="[geometry, material, count]" />
+
+<ngt-instanced-mesh *args="[undefined, undefined, count]">
+    <ngt-box-geometry />
+    <ngt-mesh-standard-material />
+</ngt-instanced-mesh>
+
+<ngt-spot-light>
+    <ngt-vector2 *args="[2048, 2048]" attach="shadow.mapSize" />
+</ngt-spot-light>
+```
+
+Please consult [THREE.js Documentation](https://threejs.org) for details on the **Construtor Arguments**

apps/documentation/docs/api/directives/repeat.mdx

@@ -0,0 +1,19 @@
+---
+id: repeat
+title: NgtRepeat
+sidebar_label: NgtRepeat
+---
+
+`NgtRepeat` is a structural directive which subclasses `NgFor` to add `ngForRepeat` Input. This is done to provide an
+easy way of looping over a number of times to render a specific amount of objects.
+
+```html
+<ngt-mesh>
+    <ngt-box-geometry />
+    <!-- a Box should have 6 faces, we want to assign an independent Material to each face -->
+    <!-- without NgtRepeat -->
+    <ngt-mesh-standard-material *ngFor="let i of [0, 1, 2, 3, 4, 5]" [attach]="['material', i]" />
+    <!-- with NgtRepeat -->
+    <ngt-mesh-standard-material *ngFor="let i; repeat 6" [attach]="['material', i]" />
+</ngt-mesh>
+```

apps/documentation/docs/api/pipes/push.mdx

@@ -0,0 +1,24 @@
+---
+id: push
+title: NgtPush
+sidebar_label: NgtPush
+---
+
+`NgtPush` is similar to Angular's `AsyncPipe`. The difference is `NgtPush` works with a CD-detached environment like
+NGT.
+
+```html
+<!-- might not work because Change Detection doesn't run -->
+<ngt-box-geometry *args="args$ | async" />
+<!-- ensures Change Detection triggers on changes -->
+<ngt-box-geometry *args="args$ | ngtPush" />
+```
+
+### Default Value
+
+`NgtPush` accepts a default value for the first emission.
+
+```html
+<!-- make a box of [2, 2, 2] by default -->
+<ngt-box-geometry *args="args$ | ngtPush: [2, 2, 2]" />
+```

apps/documentation/docs/api/primitive.mdx

@@ -0,0 +1,32 @@
+---
+id: primitive
+title: Primitive
+sidebar_label: Primitive
+---
+
+There are occasions that we need to put already-exist 3D objects on our SceneGraph (eg: an external 3D model). For this,
+we can use `<ngt-primitive>` Custom Element tag as a placeholder for our 3D objects
+
+```html
+<ngt-primitive *args="[object]" [position]="[1, 1, 1]" />
+```
+
+:::note
+
+-   `<ngt-primitive>` always requires `*args` with one item, the 3D object we want to put on the SceneGraph.
+-   We can bind Inputs/Outputs to `<ngt-primitive>` and those will be forwarded to the underlying 3D object.
+-   NGT Custom Renderer **does not** dispose `<ngt-primitive>` underlying 3D object on destroy, we have to do it manually.
+
+:::
+
+A more realistic use-case is to load a 3D model into our SceneGraph
+
+```ts
+@Component({
+    template: ` <ngt-primitive *args="[model$ | ngtPush]" [scale]="0.01" /> `,
+    imports: [NgtArgs, NgtPush],
+})
+export class SceneGraph {
+    readonly model$ = injectNgtLoader(GLTFLoader, 'assets/model.glb').pipe(map((model) => model.scene));
+}
+```

apps/documentation/docs/api/raw-value.mdx

@@ -0,0 +1,16 @@
+---
+id: raw-value
+title: Raw Value
+sidebar_label: Raw Value
+---
+
+There are occasions where we want to declaratively assign a single value to a property on a parent element, we can use
+`<ngt-value>` Custom Element tag.
+
+```html
+<!-- this saves us the trouble of getting access to the PointLight instance and assign 0.0001 to light.shadow.bias -->
+<ngt-point-light>
+    <!-- with this, we can declaratively assign a value to shadow.bias; under an ngIf or something similar -->
+    <ngt-value [rawValue]="0.0001" attach="shadow.bias" />
+</ngt-point-light>
+```

apps/documentation/docs/api/ref.mdx

@@ -3,3 +3,72 @@ id: ref
 title: Ref
 sidebar_label: Ref
 ---
+
+Ref is a concept borrowed from [React](https://beta.reactjs.org/learn/referencing-values-with-refs), but with a little twist.
+In THREE.js, it is common to mutate properties on an object rather than staying in the immutable lane that we're used to.
+And there are many sources that can mutate properties of the same object: THREE.js, Cannon.js (Physics engine), Animations (GSAP) etc...
+
+With that, NGT decides to implement the Ref concept.
+
+## `ViewChild` / `ContentChild`
+
+We can get a hold of an object on the template using the good ol' `ViewChild` or `ContentChild`
+
+```ts
+@Component({
+    template: `<ngt-mesh #mesh />`,
+})
+export class SceneGraph {
+    @ViewChild('mesh', { static: true }) mesh!: ElementRef<Mesh>;
+}
+```
+
+We can also use `ViewChildren` / `ContentChildren` if we want to interact with the [QueryList API](https://angular.io/api/core/QueryList)
+instead.
+
+## `injectNgtRef()`
+
+More than often, we want to define an **external** Ref that we can pass around. To do so, we can use `injectNgtRef()` function
+to create a Ref.
+
+```ts
+@Component({
+    template: `<ngt-mesh />`,
+})
+export class SceneGraph {
+    // highlight-next-line
+    readonly ref = injectNgtRef<Mesh>();
+}
+```
+
+Then, we pass our `ref` into the `[ref]` Input on the element.
+
+```ts
+@Component({
+    template: `
+        // highlight-next-line
+        <ngt-mesh [ref]="ref" />
+    `,
+})
+export class SceneGraph {
+    readonly ref = injectNgtRef();
+}
+```
+
+The NGT Custom Renderer will assign the `Mesh` object to the `ref.nativeElement` when it is available. `injectNgtRef()`
+returns an `NgtInjectedRef<ObjectType>`.
+
+```ts
+type Subscribe<T> = (callback: (current: T, previous: T | null) => void) => Subscription;
+
+export type NgtInjectedRef<T> = ElementRef<T> & {
+    /* a Subscribe fn that emits current and previous value. Useful for debug */
+    subscribe: Subscribe<T>;
+    /* consumers should use this for listening to value of this ref. This filters out initial null value */
+    $: Observable<T>;
+    /* consumers should use this for listenting to children changes on this ref */
+    children$: (type?: 'objects' | 'nonObjects' | 'both') => Observable<NgtInstanceNode[]>;
+    /* notify this CD when ref value changes */
+    useCDR: (cdr: ChangeDetectorRef) => void;
+};
+```title

apps/documentation/docs/api/store.mdx

@@ -0,0 +1,69 @@
+---
+id: store
+title: Store
+sidebar_label: Store
+---
+
+`NgtStore` contains all information about the current `NgtCanvas`. `NgtStore` extends [RxState](https://www.rx-angular.io/docs/state/api/rx-state) API
+
+```ts
+@Component({
+    /*...*/
+})
+export class SceneGraph {
+    // inject the Store. We can also use Constructor DI
+    readonly store = inject(NgtStore);
+}
+```
+
+## Select states reactively
+
+```ts
+@Component({
+    /*...*/
+})
+export class SceneGraph {
+    readonly store = inject(NgtStore);
+    readonly camera$ = this.store.select('camera'); // Observable<NgtCamera>
+    readonly glDom$ = this.store.select('gl', 'domElement'); // Observable<HTMLElement>
+}
+```
+
+## Get states imperatively
+
+```ts
+@Component({
+    /*...*/
+})
+export class SceneGraph {
+    readonly store = inject(NgtStore);
+    readonly camera = this.store.get('camera'); // NgtCamera
+    readonly glDom = this.store.get('gl', 'domElement'); // HTMLElement
+}
+```
+
+## Register before render callbacks
+
+Beside using `(beforeRender)` Output on Custom Element tags, we can also use `NgtStore` to register a before render callback
+
+```ts
+@Component({
+    /*...*/
+})
+export class SceneGraph {
+    readonly store = inject(NgtStore);
+
+    private sub?: () => void;
+
+    ngOnInit() {
+        // register and return the clean up function
+        // signature: subscribe(callback, priority)
+        this.sub = this.store.get('internal').subscribe(() => {}, 0);
+    }
+
+    ngOnDestroy() {
+        // call the clean up function to unregister the callback
+        this.sub?.();
+    }
+}
+```

apps/documentation/sidebars.js

@@ -22,7 +22,25 @@ const sidebars = {
         {
             type: 'category',
             label: 'API',
-            items: ['api/canvas', 'api/custom-renderer', 'api/ref'],
+            items: [
+                'api/canvas',
+                'api/custom-renderer',
+                {
+                    type: 'category',
+                    label: 'Directives',
+                    items: ['api/directives/args', 'api/directives/repeat'],
+                },
+                {
+                    type: 'category',
+                    label: 'Pipes',
+                    items: ['api/pipes/push'],
+                },
+                'api/ref',
+                'api/primitive',
+                'api/raw-value',
+                'api/store',
+                'api/additional-exports',
+            ],
         },
     ],
     // By default, Docusaurus generates a sidebar from the docs folder structure

apps/documentation/src/pages/index.js

@@ -1,4 +1,3 @@
-import React from 'react';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Layout from '@theme/Layout';
@@ -19,7 +18,7 @@ function HomepageHeader() {
                     <small>"What happened to Angular 3.0? Well, it became Angular Three" - Mike Hartington</small>
                 </em>
                 <div className={styles.buttons}>
-                    <Link className="button button--secondary button--lg" to="/docs/getting-started/overview">
+                    <Link className="button button--secondary button--lg" to="/docs/getting-started/introduction">
                         Get Started
                     </Link>
                 </div>