feat: add controllable state reducer utility

Author: unadlib

packages/use-controllable-state/README.md

@@ -1,3 +1,9 @@
 # @fictjs/use-controllable-state
 
-A Fict-native controllable state helper inspired by `@radix-ui/react-use-controllable-state`. It returns an accessor for the current value plus a setter that supports controlled and uncontrolled flows.
+Fict-native controllable state helpers inspired by
+`@radix-ui/react-use-controllable-state`.
+
+Exports:
+
+- `useControllableState`
+- `useControllableStateReducer`

packages/use-controllable-state/src/index.ts

@@ -15,6 +15,7 @@ import { useLayoutEffect } from '@fictjs/use-layout-effect'
 
 type ChangeHandler<T> = (state: T) => void
 type SetStateFn<T> = (value: T | ((prev: T) => T)) => void
+type Dispatch<A> = (action: A) => void
 
 interface UseControllableStateParams<T> {
   prop?: MaybeAccessor<T | undefined>
@@ -23,6 +24,10 @@ interface UseControllableStateParams<T> {
   caller?: string
 }
 
+type AnyAction = {
+  type: string
+}
+
 const noop = () => {}
 
 function useControllableState<T>({
@@ -81,5 +86,84 @@ function useControllableState<T>({
   return [value, setValue]
 }
 
-export { useControllableState }
-export type { ChangeHandler, SetStateFn, UseControllableStateParams }
+function useControllableStateReducer<T, S extends object, A extends AnyAction>(
+  reducer: (prevState: S & { state: T }, action: A) => S & { state: T },
+  userArgs: UseControllableStateParams<T>,
+  initialState: Omit<S, 'state'>,
+): [() => S & { state: T }, Dispatch<A>]
+function useControllableStateReducer<T, S extends object, I extends object, A extends AnyAction>(
+  reducer: (prevState: S & { state: T }, action: A) => S & { state: T },
+  userArgs: UseControllableStateParams<T>,
+  initialArg: I,
+  init: (value: I & { state: T }) => Omit<S, 'state'>,
+): [() => S & { state: T }, Dispatch<A>]
+function useControllableStateReducer<T, S extends object, I extends object, A extends AnyAction>(
+  reducer: (prevState: S & { state: T }, action: A) => S & { state: T },
+  { prop, defaultProp, onChange = noop as ChangeHandler<T>, caller }: UseControllableStateParams<T>,
+  initialArg: Omit<S, 'state'> | I,
+  init?: (value: I & { state: T }) => Omit<S, 'state'>,
+): [() => S & { state: T }, Dispatch<A>] {
+  const defaultState = () => readValue(defaultProp)
+  const controlledState = () => (prop === undefined ? undefined : readValue(prop))
+  const emitChange = useEffectEvent(onChange)
+  const createInitialState = (): S & { state: T } => {
+    const state = defaultState()
+    const baseState = init
+      ? init({ ...(initialArg as I), state })
+      : (initialArg as Omit<S, 'state'>)
+
+    return { ...baseState, state } as S & { state: T }
+  }
+  const internalState = createSignal<S & { state: T }>(createInitialState())
+
+  let lastMode = controlledState() !== undefined
+  useLayoutEffect(() => {
+    const nextMode = controlledState() !== undefined
+
+    if (process.env.NODE_ENV !== 'production' && lastMode !== nextMode) {
+      const from = lastMode ? 'controlled' : 'uncontrolled'
+      const to = nextMode ? 'controlled' : 'uncontrolled'
+      const label = caller ?? 'useControllableStateReducer'
+      console.warn(
+        label +
+          ' is changing from ' +
+          from +
+          ' to ' +
+          to +
+          '. Components should stay either controlled or uncontrolled for their lifetime.',
+      )
+    }
+
+    lastMode = nextMode
+  })
+
+  const state = () => {
+    const currentInternalState = internalState()
+    const currentProp = controlledState()
+
+    if (currentProp === undefined) {
+      return currentInternalState
+    }
+
+    return {
+      ...currentInternalState,
+      state: currentProp,
+    }
+  }
+
+  const dispatch: Dispatch<A> = (action) => {
+    const prevState = state()
+    const nextState = reducer(prevState, action)
+
+    internalState(nextState)
+
+    if (!Object.is(prevState.state, nextState.state)) {
+      emitChange(nextState.state)
+    }
+  }
+
+  return [state, dispatch]
+}
+
+export { useControllableState, useControllableStateReducer }
+export type { AnyAction, ChangeHandler, Dispatch, SetStateFn, UseControllableStateParams }

packages/use-controllable-state/test/index.test.tsx

@@ -5,7 +5,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { render } from '@fictjs/runtime'
 import { createSignal } from '@fictjs/runtime/advanced'
 
-import { useControllableState } from '../src/index.js'
+import { useControllableState, useControllableStateReducer } from '../src/index.js'
 
 describe('@fictjs/use-controllable-state', () => {
   it('updates uncontrolled state and emits changes', () => {
@@ -40,4 +40,85 @@ describe('@fictjs/use-controllable-state', () => {
     expect(value?.()).toBe('first')
     expect(onChange).toHaveBeenCalledWith('second')
   })
+
+  it('updates reducer state for uncontrolled usage', () => {
+    type ReducerState = {
+      count: number
+      state: string
+    }
+    type ReducerAction = {
+      type: 'increment'
+    } | {
+      type: 'select'
+      value: string
+    }
+
+    let state: (() => ReducerState) | undefined
+    let dispatch: ((action: ReducerAction) => void) | undefined
+    const onChange = vi.fn()
+
+    render(() => {
+      ;[state, dispatch] = useControllableStateReducer<string, Omit<ReducerState, 'state'>, ReducerAction>(
+        (prevState, action) => {
+          if (action.type === 'increment') {
+            return { ...prevState, count: prevState.count + 1 }
+          }
+
+          return { ...prevState, state: action.value }
+        },
+        { defaultProp: 'alpha', onChange },
+        { count: 0 },
+      )
+      return <div />
+    }, document.createElement('div'))
+
+    expect(state?.()).toEqual({ count: 0, state: 'alpha' })
+
+    dispatch?.({ type: 'increment' })
+    expect(state?.()).toEqual({ count: 1, state: 'alpha' })
+
+    dispatch?.({ type: 'select', value: 'beta' })
+    expect(state?.()).toEqual({ count: 1, state: 'beta' })
+    expect(onChange).toHaveBeenCalledWith('beta')
+  })
+
+  it('emits reducer state changes while preserving controlled value reads', () => {
+    type ReducerState = {
+      count: number
+      state: string
+    }
+    type ReducerAction = {
+      type: 'increment'
+    } | {
+      type: 'select'
+      value: string
+    }
+
+    const controlled = createSignal('first')
+    let state: (() => ReducerState) | undefined
+    let dispatch: ((action: ReducerAction) => void) | undefined
+    const onChange = vi.fn()
+
+    render(() => {
+      ;[state, dispatch] = useControllableStateReducer<string, Omit<ReducerState, 'state'>, ReducerAction>(
+        (prevState, action) => {
+          if (action.type === 'increment') {
+            return { ...prevState, count: prevState.count + 1 }
+          }
+
+          return { ...prevState, state: action.value }
+        },
+        { prop: () => controlled(), defaultProp: 'fallback', onChange },
+        { count: 0 },
+      )
+      return <div />
+    }, document.createElement('div'))
+
+    dispatch?.({ type: 'increment' })
+    expect(state?.()).toEqual({ count: 1, state: 'first' })
+
+    dispatch?.({ type: 'select', value: 'second' })
+    expect(state?.()).toEqual({ count: 1, state: 'first' })
+    expect(onChange).toHaveBeenCalledWith('second')
+  })
 })