feat: add clearPath, clearOnUnmount option, and store lifecycle tests

- Add `store.clearPath(path)` to hard-delete a cached path, guarded by
  `__refCount` so it's a no-op while the path is still mounted
- Add `clearOnUnmount?: boolean` per-input schema option that
  automatically clears the path when the component unmounts
- Use a `Set` for clearOnUnmountPaths so add/remove correctly handles
  dynamic changes to the option between renders
- Add integration tests covering mount/unmount lifecycle, nested folder
  paths, value preservation, and both clearOnUnmount mechanisms

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: RodrigoHamuy

packages/leva/src/types/internal.ts

@@ -20,6 +20,7 @@ export type MappedPaths = Record<
     onEditStart?: (...args: any) => void
     onEditEnd?: (...args: any) => void
     transient: boolean
+    clearOnUnmount: boolean
   }
 >
 

packages/leva/src/types/public.ts

@@ -185,6 +185,7 @@ export type InputOptions = GenericSchemaItemOptions &
     disabled?: boolean
     onEditStart?: (value: any, path: string, context: OnHandlerContext) => void
     onEditEnd?: (value: any, path: string, context: OnHandlerContext) => void
+    clearOnUnmount?: boolean
   }
 
 type SchemaItemWithOptions =

packages/leva/src/useControls.test.tsx

@@ -18,7 +18,7 @@ vi.mock('@stitches/react', () => ({
   }),
 }))
 
-import React from 'react'
+import React, { useEffect } from 'react'
 import { describe, it, expect, vi, afterEach } from 'vitest'
 import { render, act } from '@testing-library/react'
 import { useControls } from './useControls'
@@ -38,6 +38,17 @@ function NestedNumberComponent({ id }: { id?: string }) {
   return <div data-testid={id ?? 'value'}>{myNumber}</div>
 }
 
+function NumberComponentClearOnUnmount({ id }: { id?: string }) {
+  const { myNumber } = useControls({ myNumber: 5 }, { headless: true })
+  useEffect(() => () => { levaStore.clearPath('myNumber') }, [])
+  return <div data-testid={id ?? 'value'}>{myNumber}</div>
+}
+
+function ClearOnUnmountOptionComponent({ id }: { id?: string }) {
+  const { myNumber } = useControls({ myNumber: { value: 5, clearOnUnmount: true } }, { headless: true })
+  return <div data-testid={id ?? 'value'}>{myNumber}</div>
+}
+
 describe('useControls mount/unmount lifecycle', () => {
   it('does not clear a path that is still mounted', () => {
     const { unmount } = render(<NumberComponent id="value" />)
@@ -53,7 +64,7 @@ describe('useControls mount/unmount lifecycle', () => {
     unmount()
   })
 
-  it('works with nested folder paths', async () => {
+  it('works with nested folder paths', () => {
     const { getByTestId, unmount } = render(<NestedNumberComponent id="value" />)
     expect(getByTestId('value').textContent).toBe('5')
 
@@ -69,24 +80,61 @@ describe('useControls mount/unmount lifecycle', () => {
     expect(getByTestId2('value2').textContent).toBe('5')
   })
 
-  it('resets to the initial value when remounted after clearPath', async () => {
-    // Mount the component
+  it('preserves the value on remount when not cleared', () => {
+    const { unmount } = render(<NumberComponent id="value" />)
+
+    act(() => {
+      levaStore.setValueAtPath('myNumber', 42, true)
+    })
+
+    act(() => unmount())
+
+    // value survives unmount without clearing
+    expect(levaStore.get('myNumber')).toBe(42)
+  })
+
+  it('useEffect clearPath resets the value on remount', () => {
+    const { getByTestId, unmount } = render(<NumberComponentClearOnUnmount id="value" />)
+    expect(getByTestId('value').textContent).toBe('5')
+
+    act(() => {
+      levaStore.setValueAtPath('myNumber', 42, true)
+    })
+    expect(getByTestId('value').textContent).toBe('42')
+
+    act(() => unmount())
+
+    const { getByTestId: getByTestId2 } = render(<NumberComponentClearOnUnmount id="value2" />)
+    expect(getByTestId2('value2').textContent).toBe('5')
+  })
+
+  it('clearOnUnmount option resets the value on remount', () => {
+    const { getByTestId, unmount } = render(<ClearOnUnmountOptionComponent id="value" />)
+    expect(getByTestId('value').textContent).toBe('5')
+
+    act(() => {
+      levaStore.setValueAtPath('myNumber', 42, true)
+    })
+    expect(getByTestId('value').textContent).toBe('42')
+
+    act(() => unmount())
+
+    const { getByTestId: getByTestId2 } = render(<ClearOnUnmountOptionComponent id="value2" />)
+    expect(getByTestId2('value2').textContent).toBe('5')
+  })
+
+  it('resets to the initial value when remounted after clearPath', () => {
     const { getByTestId, unmount } = render(<NumberComponent id="value" />)
     expect(getByTestId('value').textContent).toBe('5')
 
-    // Simulate a value change via the store (as if the user dragged the slider)
     act(() => {
       levaStore.setValueAtPath('myNumber', 42, true)
     })
     expect(getByTestId('value').textContent).toBe('42')
 
-    // Unmount – disposePaths decrements __refCount to 0 but the value stays in the store
     unmount()
-
-    // Clear the cached value so the next mount starts fresh
     levaStore.clearPath('myNumber')
 
-    // Remount – useControls reads from the schema (value: 5) because the path is gone
     const { getByTestId: getByTestId2 } = render(<NumberComponent id="value2" />)
     expect(getByTestId2('value2').textContent).toBe('5')
   })

packages/leva/src/useControls.ts

@@ -133,14 +133,15 @@ export function useControls<S extends Schema, F extends SchemaOrFn<S> | string,
    * parses the schema inside nested folder.
    */
   const [initialData, mappedPaths] = useMemo(() => store.getDataFromSchema(_schema), [store, _schema])
-  const [allPaths, renderPaths, onChangePaths, onEditStartPaths, onEditEndPaths] = useMemo(() => {
+  const [allPaths, renderPaths, onChangePaths, onEditStartPaths, onEditEndPaths, clearOnUnmountPaths] = useMemo(() => {
     const allPaths: string[] = []
     const renderPaths: string[] = []
     const onChangePaths: Record<string, OnChangeHandler> = {}
     const onEditStartPaths: Record<string, (...args: any) => void> = {}
     const onEditEndPaths: Record<string, (...args: any) => void> = {}
+    const clearOnUnmountPaths = new Set<string>()
 
-    Object.values(mappedPaths).forEach(({ path, onChange, onEditStart, onEditEnd, transient }) => {
+    Object.values(mappedPaths).forEach(({ path, onChange, onEditStart, onEditEnd, transient, clearOnUnmount }) => {
       allPaths.push(path)
       if (onChange) {
         onChangePaths[path] = onChange
@@ -157,8 +158,13 @@ export function useControls<S extends Schema, F extends SchemaOrFn<S> | string,
       if (onEditEnd) {
         onEditEndPaths[path] = onEditEnd
       }
+      if (clearOnUnmount) {
+        clearOnUnmountPaths.add(path)
+      } else {
+        clearOnUnmountPaths.delete(path)
+      }
     })
-    return [allPaths, renderPaths, onChangePaths, onEditStartPaths, onEditEndPaths]
+    return [allPaths, renderPaths, onChangePaths, onEditStartPaths, onEditEndPaths, clearOnUnmountPaths]
   }, [mappedPaths])
 
   // Extracts the paths from the initialData and ensures order of paths.
@@ -199,8 +205,11 @@ export function useControls<S extends Schema, F extends SchemaOrFn<S> | string,
     store.addData(initialData, shouldOverrideSettings)
     firstRender.current = false
     depsChanged.current = false
-    return () => store.disposePaths(paths)
-  }, [store, paths, initialData])
+    return () => {
+      store.disposePaths(paths)
+      clearOnUnmountPaths.forEach((path) => store.clearPath(path))
+    }
+  }, [store, paths, initialData, clearOnUnmountPaths])
 
   useEffect(() => {
     // let's handle transient subscriptions

packages/leva/src/utils/data.ts

@@ -65,9 +65,9 @@ export function getDataFromSchema(
       if (normalizedInput) {
         const { type, options, input } = normalizedInput
         // @ts-ignore
-        const { onChange, transient, onEditStart, onEditEnd, ..._options } = options
+        const { onChange, transient, onEditStart, onEditEnd, clearOnUnmount, ..._options } = options
         data[newPath] = { type, ..._options, ...input, fromPanel: true }
-        mappedPaths[key] = { path: newPath, onChange, transient, onEditStart, onEditEnd }
+        mappedPaths[key] = { path: newPath, onChange, transient, onEditStart, onEditEnd, clearOnUnmount: clearOnUnmount ?? false }
       } else {
         warn(LevaErrors.UNKNOWN_INPUT, newPath, rawInput)
       }

packages/leva/src/utils/input.ts

@@ -65,6 +65,7 @@ export function parseOptions(
     onEditStart,
     onEditEnd,
     transient,
+    clearOnUnmount,
     ...inputWithType
   } = _input
 
@@ -79,6 +80,7 @@ export function parseOptions(
     disabled,
     optional,
     order,
+    clearOnUnmount,
     ...mergedOptions,
   }