feat!: deprecate useSeek composable and update documentation (#990)

* feat!: deprecate useSeek composable and update documentation

BREAKING CHANGE: `useSeek` is deprecated

- Marked the `useSeek` composable as deprecated in the documentation, indicating its removal in v5.0.0.
- Removed the `useSeek` composable implementation and its associated tests from the codebase to streamline the composables directory.
- Updated the documentation to reflect the deprecation status and provide guidance for users.

* Update docs/api/composables.md

Co-authored-by: Tino Koch <17991193+Tinoooo@users.noreply.github.com>

---------

Co-authored-by: Tino Koch <17991193+Tinoooo@users.noreply.github.com>

docs/api/composables.md

@@ -359,7 +359,11 @@ You can also use `UseTexture` (with uppercase) as component like so:
 The `UseTexture` component needs to be wrapped in a `Suspense` component in order to work
 :::
 
-## useSeek
+## useSeek <Badge text="deprecated" />
+
+::: danger
+This composable is deprecated as of version 5.0.0.
+:::
 
 The `useSeek` composable provides utilities to easily traverse and navigate through complex ThreeJS scenes and object children graphs. It exports 4 functions which allow you to find child objects based on specific properties.
 

src/composables/index.ts

@@ -8,7 +8,6 @@ export * from './useLoop'
 export * from './useRaycaster'
 export * from './useRenderer/'
 export * from './useRenderLoop'
-export * from './useSeek'
 export * from './useTexture'
 export * from './useTresContextProvider'
 export * from './useTresEventManager'

src/composables/useSeek/index.ts

@@ -1,100 +0,0 @@
-import type { Object3D, Scene } from 'three'
-import { logWarning } from '../../utils/logger'
-
-/**
- * Seek composable return type
- *
- * @export
- * @interface UseSeekReturn
- */
-export interface UseSeekReturn {
-  seek: (parent: Scene | Object3D, property: string, value: string) => Object3D | null
-  seekByName: (parent: Scene | Object3D, value: string) => Object3D | null
-  seekAll: (parent: Scene | Object3D, property: string, value: string) => Object3D[]
-  seekAllByName: (parent: Scene | Object3D, value: string) => Object3D[]
-}
-
-/**
- * Composable that provides utilities to easily traverse and navigate through complex scenes and object children graphs
- *
- * @export
- * @return {*}  {UseSeekReturn}
- */
-export function useSeek(): UseSeekReturn {
-  /**
-   * Returns a child object of the parent given a property
-   *
-   * @param {(Scene | Object3D)} parent
-   * @param {string} property
-   * @param {string} value
-   * @return {*}  {(Object3D | null)}
-   */
-  function seek(parent: Scene | Object3D, property: string, value: string): Object3D | null {
-    let foundChild: Object3D | null = null
-
-    parent.traverse((child) => {
-      if ((child as any)[property] === value) {
-        foundChild = child
-      }
-    })
-
-    if (!foundChild) {
-      logWarning(`Child with ${property} '${value}' not found.`)
-    }
-
-    return foundChild
-  }
-
-  /**
-   * Returns an array of child objects of the parent given a property
-   *
-   * @param {(Scene | Object3D)} parent
-   * @param {string} property
-   * @param {string} value
-   * @return {*}  {(Object3D[])}
-   */
-  function seekAll(parent: Scene | Object3D, property: string, value: string): Object3D[] {
-    const foundChildren: Object3D[] = []
-
-    parent.traverse((child) => {
-      if ((child as any)[property].includes(value)) {
-        foundChildren.push(child)
-      }
-    })
-
-    if (!foundChildren.length) {
-      logWarning(`Children with ${property} '${value}' not found.`)
-    }
-
-    return foundChildren
-  }
-
-  /**
-   * Returns a child object of the parent given a child.name
-   *
-   * @param {(Scene | Object3D)} parent
-   * @param {string} value
-   * @return {*}  {(Object3D | null)}
-   */
-  function seekByName(parent: Scene | Object3D, value: string): Object3D | null {
-    return seek(parent, 'name', value)
-  }
-
-  /**
-   * Returns an array of child objects of the parent given a child.name
-   *
-   * @param {(Scene | Object3D)} parent
-   * @param {string} value
-   * @return {*}  {(Object3D[])}
-   */
-  function seekAllByName(parent: Scene | Object3D, value: string): Object3D[] {
-    return seekAll(parent, 'name', value)
-  }
-
-  return {
-    seek,
-    seekByName,
-    seekAll,
-    seekAllByName,
-  }
-}

src/composables/useSeek/useSeek.test.ts

@@ -1,31 +0,0 @@
-import { Object3D } from 'three'
-import { useSeek } from '.'
-import { withSetup } from '../../utils/test-utils'
-
-const [composable, app] = withSetup(() => useSeek())
-
-describe('useSeek', () => {
-  afterEach(() => {
-    app.unmount()
-  })
-  it('should find a child by a property', () => {
-    const { seek } = composable
-    const parent = new Object3D()
-    const child = new Object3D()
-    ;(child as any).customProperty = 'customValue'
-    parent.add(child)
-
-    const result = seek(parent, 'customProperty', 'customValue')
-    expect(result).toBe(child)
-  })
-  it('should find a child by a name', () => { // Renamed the test case to have a different name
-    const { seekByName } = composable
-    const parent = new Object3D()
-    const child = new Object3D()
-    child.name = 'testChild'
-    parent.add(child)
-
-    const result = seekByName(parent, 'testChild')
-    expect(result).toBe(child)
-  })
-})