fix(core): rename selection apis

Author: nartc

apps/examples/src/app/postprocessing/outline/scene.ts

@@ -1,21 +1,22 @@
 import { ChangeDetectionStrategy, Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';
-import { NgtArgs, NgtSelect, NgtSelection } from 'angular-three';
+import { NgtArgs, NgtSelection, NgtSelectionApi } from 'angular-three';
 import { NgtpEffectComposer, NgtpOutline, NgtpSMAA } from 'angular-three-postprocessing';
 import { NgtsOrbitControls } from 'angular-three-soba/controls';
 import { KernelSize } from 'postprocessing';
 
 /**
  * There are multiple ways to use the Outline effect.
  *
- * 1. Via NgtSelection and NgtSelect
+ * 1. Via NgtSelectionApi and NgtSelect
  *    This is the recommended way to use the Outline effect.
  *
- *    1a. We can use NgtSelection as hostDirective (as shown) to enable Selection on the entire scene.
+ *    1a. We can use NgtSelectionApi as hostDirective (as shown) to enable Selection on the entire scene.
  *        NgtpOutline will automatically be aware of the NgtSelection context and will use it for the selected objects.
  *
- *    1b. We can wrap `<ng-container ngtSelection>` around the objects we want to select AS WELL AS the Outline effect.
+ *    1b. We can wrap `<ng-container selection>` around the objects we want to select AS WELL AS the Outline effect.
+ *        When using this approach, you can use `NgtSelection` in the imports array instead of [NgtSelectionApi, NgtSelect].
  *
- *    ngtSelect can be used on ngt-group or ngt-mesh. ngt-group will select all children, ngt-mesh will only select itself.
+ *    select can be used on ngt-group or ngt-mesh. ngt-group will select all children, ngt-mesh will only select itself.
  *
  * 2. Via selection input on NgtpOutline
  *    If we want to control the selection ourselves, we can pass in the selection input an Array of Object3D or ElementRef<Object3D>
@@ -36,7 +37,7 @@ import { KernelSize } from 'postprocessing';
 		<ngt-point-light [position]="[0, -1, -1]" [decay]="0" color="green" />
 		<ngt-directional-light [position]="[0, 1, 1]" />
 
-		<ngt-group [ngtSelect]="hovered()" (pointerenter)="hovered.set(true)" (pointerleave)="hovered.set(false)">
+		<ngt-group [select]="hovered()" (pointerenter)="hovered.set(true)" (pointerleave)="hovered.set(false)">
 			<ngt-mesh>
 				<ngt-box-geometry />
 				<ngt-mesh-standard-material color="hotpink" />
@@ -59,8 +60,8 @@ import { KernelSize } from 'postprocessing';
 	schemas: [CUSTOM_ELEMENTS_SCHEMA],
 	changeDetection: ChangeDetectionStrategy.OnPush,
 	host: { class: 'postprocessing-sample' },
-	hostDirectives: [NgtSelection],
-	imports: [NgtsOrbitControls, NgtSelect, NgtpEffectComposer, NgtpOutline, NgtArgs, NgtpSMAA],
+	hostDirectives: [NgtSelectionApi],
+	imports: [NgtsOrbitControls, NgtSelection, NgtpEffectComposer, NgtpOutline, NgtArgs, NgtpSMAA],
 })
 export class SceneGraph {
 	protected KernelSize = KernelSize;

libs/core/src/lib/directives/selection.ts

@@ -2,9 +2,9 @@ import { booleanAttribute, Directive, effect, ElementRef, inject, input, signal,
 import { Group, Mesh, Object3D } from 'three';
 import { getInstanceState } from '../instance';
 
-@Directive({ selector: '[ngtSelection]' })
-export class NgtSelection {
-	enabled = input(true, { alias: 'ngtSelection', transform: booleanAttribute });
+@Directive({ selector: '[selection]' })
+export class NgtSelectionApi {
+	enabled = input(true, { alias: 'selection', transform: booleanAttribute });
 
 	private source = signal<Array<ElementRef<Object3D> | Object3D>>([]);
 	selected = this.source.asReadonly();
@@ -15,16 +15,16 @@ export class NgtSelection {
 	}
 }
 
-@Directive({ selector: 'ngt-group[ngtSelect], ngt-mesh[ngtSelect]' })
+@Directive({ selector: 'ngt-group[select], ngt-mesh[select]' })
 export class NgtSelect {
-	enabled = input(false, { transform: booleanAttribute, alias: 'ngtSelect' });
+	enabled = input(false, { transform: booleanAttribute, alias: 'select' });
 
 	constructor() {
 		const elementRef = inject<ElementRef<Group | Mesh>>(ElementRef);
-		const selection = inject(NgtSelection);
+		const selectionApi = inject(NgtSelectionApi);
 
 		effect((onCleanup) => {
-			const selectionEnabled = selection.enabled();
+			const selectionEnabled = selectionApi.enabled();
 			if (!selectionEnabled) return;
 
 			const enabled = this.enabled();
@@ -36,14 +36,14 @@ export class NgtSelect {
 			const localState = getInstanceState(host);
 			if (!localState) return;
 
-			// ngt-mesh[ngtSelect]
+			// ngt-mesh[select]
 			if (host.type === 'Mesh') {
-				selection.update((prev) => [...prev, host]);
-				onCleanup(() => selection.update((prev) => prev.filter((el) => el !== host)));
+				selectionApi.update((prev) => [...prev, host]);
+				onCleanup(() => selectionApi.update((prev) => prev.filter((el) => el !== host)));
 				return;
 			}
 
-			const [collection] = [untracked(selection.selected), localState.objects()];
+			const [collection] = [untracked(selectionApi.selected), localState.objects()];
 			let changed = false;
 			const current: Object3D[] = [];
 			host.traverse((child) => {
@@ -53,10 +53,12 @@ export class NgtSelect {
 
 			if (!changed) return;
 
-			selection.update((prev) => [...prev, ...current]);
+			selectionApi.update((prev) => [...prev, ...current]);
 			onCleanup(() => {
-				selection.update((prev) => prev.filter((el) => !current.includes(el as Object3D)));
+				selectionApi.update((prev) => prev.filter((el) => !current.includes(el as Object3D)));
 			});
 		});
 	}
 }
+
+export const NgtSelection = [NgtSelectionApi, NgtSelect] as const;