react-store-input 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,7 +5,29 @@ All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project uses [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.5.0] - 2026-07-31
+
+### Changed
+
+- Replaced `useStoreController` with `useStoreBinding`, a Lens/Codec-based
+  adapter for synchronizing external controls without exposing whole-state
+  subscription and draft callbacks.
+- Reimplemented `useStoreHTMLElement` and the optional `TextEditor` integration
+  on top of `useStoreBinding`.
+- Renamed `useStoreComponent` to `useStoreInput`. It accepts an existing
+  `gw-store` `Store` and returns bound `input`, `select`, and `textarea`
+  components.
+- Renamed the low-level DOM binding hook from `useStoreInput` to
+  `useStoreHTMLElement`.
+- Removed `gw-store` API re-exports. Import stores, selectors, and their types
+  directly from `gw-store`.
+
+### Removed
+
+- Removed the deprecated `useFormStore`, `FormStore`, and `FormComponents`
+  APIs.
+- Removed `useStoreController`. Non-input actions should call
+  `store.dispatch` directly.
 
 ## [0.4.0] - 2026-07-22
 

package/README.md

@@ -13,10 +13,11 @@ npm install react-store-input
 ## Quick start
 
 ```tsx
-import { useFormStore } from "react-store-input";
+import { useStore } from "gw-store";
+import { Input } from "react-store-input";
 
 export default function LoginForm() {
-  const form = useFormStore({
+  const store = useStore({
     email: "",
     password: "",
     rememberMe: false,
@@ -26,28 +27,28 @@ export default function LoginForm() {
     <form
       onSubmit={(event) => {
         event.preventDefault();
-        console.log(form.state);
+        console.log(store.state);
       }}
     >
-      <form.input name="email" type="email" />
-      <form.input name="password" type="password" />
-      <form.input name="rememberMe" type="checkbox" />
+      <Input store={store} name="email" type="email" />
+      <Input store={store} name="password" type="password" />
+      <Input store={store} name="rememberMe" type="checkbox" />
       <button type="submit">Sign in</button>
     </form>
   );
 }
 ```
 
-`useFormStore` returns the complete `gw-store` API (`state`, `dispatch`,
-`batch`, and `subscribe`) together with stable `input`, `select`, `textarea`,
-and `render` helpers.
+Create and own stores with `gw-store`. This package only binds that store to
+input controls.
 
 ## Components
 
 You can use the standalone components when the store is passed from elsewhere:
 
 ```tsx
-import { Input, Select, Textarea, useStore } from "react-store-input";
+import { useStore } from "gw-store";
+import { Input, Select, Textarea } from "react-store-input";
 
 const store = useStore({ role: "user", bio: "" });
 
@@ -60,8 +61,23 @@ const store = useStore({ role: "user", bio: "" });
 <Textarea store={store} name="bio" rows={5} />;
 ```
 
+When passing `store` to every control would be repetitive, `useStoreInput`
+returns stable components already bound to an existing store:
+
+```tsx
+import { useStore } from "gw-store";
+import { useStoreInput } from "react-store-input";
+
+const store = useStore({ role: "user", bio: "" });
+const controls = useStoreInput(store);
+
+<controls.input name="role" />;
+<controls.select name="role">...</controls.select>;
+<controls.textarea name="bio" />;
+```
+
 A named `Input`, `Select`, or `Textarea` requires a valid top-level state key.
-Use `useStoreInput` with a typed binding for nested or converted values.
+Use `useStoreHTMLElement` with a typed binding for nested or converted values.
 
 ## Value conversion
 
@@ -93,7 +109,7 @@ A custom control is defined from three small pieces:
 
 Keeping the lens and codec separate lets one state field use different UI
 representations, and lets one codec be reused for the same domain type in
-different stores.
+different stores. `InputBinding` itself is not tied to an HTML element.
 
 ```tsx
 import {
@@ -132,10 +148,11 @@ codec implementations.
 
 ## Rendering selected state
 
-`useSelector`, `shallowEqual`, and the rest of `gw-store@0.2.0` are re-exported.
+Use `gw-store` selectors with this package's rendering helper.
 
 ```tsx
-import { createRender, useSelector } from "react-store-input";
+import { useSelector } from "gw-store";
+import { createRender } from "react-store-input";
 
 const email = useSelector(store, (state) => state.email);
 
@@ -143,25 +160,30 @@ return (
   <>
     <p>{email}</p>
     {createRender(store, (state) => <p>{state.password.length} characters</p>)}
-    {form.render((state) => <p>{state.rememberMe ? "Remember" : "Forget"}</p>)}
+    {createRender(store, (state) => (
+      <p>{state.rememberMe ? "Remember" : "Forget"}</p>
+    ))}
   </>
 );
 ```
 
 ## Custom controls
 
-Use `useStoreInput` with a binding for custom elements that expose a normal
+Use `useStoreHTMLElement` with a binding for custom elements that expose a normal
 form-control DOM node. The ref is deliberately explicit. A parse failure keeps
 the last valid store value, preserves the user's raw input, and exposes the
 typed error through `meta`.
 
 ```tsx
 import { useRef } from "react";
-import { useStoreInput, type Store } from "react-store-input";
+import type { Store } from "gw-store";
+import { useStoreHTMLElement } from "react-store-input";
 
 function BudgetInput({ store }: { store: Store<FormState> }) {
   const ref = useRef<HTMLInputElement>(null);
-  const field = useStoreInput(ref, store, budgetBinding, { type: "text" });
+  const field = useStoreHTMLElement(ref, store, budgetBinding, {
+    type: "text",
+  });
 
   return (
     <label>
@@ -179,6 +201,21 @@ function BudgetInput({ store }: { store: Store<FormState> }) {
 }
 ```
 
+For an imperative editor or another non-DOM control, use the same binding
+through `useStoreBinding`. It parses commits, exposes validation metadata, and
+synchronizes external store changes without echoing its own dispatch:
+
+```tsx
+const field = useStoreBinding(store, budgetBinding, {
+  onStoreChange: (input) => editorRef.current?.setValue(input),
+});
+
+<ExternalEditor
+  defaultValue={field.initialValue}
+  onChange={(input) => field.commit(input)}
+/>;
+```
+
 Generated lenses and codecs can be checked with the exported law assertions in
 unit tests:
 
@@ -200,21 +237,18 @@ values, plus `format(parse(input).value)` for successful canonical inputs when
 `inputs` are supplied. Normalizing or lossy codecs may supply domain-specific
 `equals` and `equalsInput` functions.
 
-For non-input controllers, call the returned `dispatch` when the controller
-changes:
+For non-input actions, dispatch directly to the store:
 
 ```tsx
-import { useStoreController } from "react-store-input";
+import type { Store } from "gw-store";
 
 function Counter({ store }: { store: Store<{ count: number }> }) {
-  const { dispatch } = useStoreController(store, {
-    onSubscribe: () => {},
-    onDispatch: (state) => {
+  const increment = () =>
+    store.dispatch((state) => {
       state.count += 1;
-    },
-  });
+    });
 
-  return <button onClick={dispatch}>Increment</button>;
+  return <button onClick={increment}>Increment</button>;
 }
 ```
 
@@ -244,8 +278,8 @@ Source code is grouped by responsibility:
 ```text
 src/
 ├─ binding/ Lens, Codec, Binding, and law assertions
-├─ input/   DOM value conversion, reset coordination, and input hooks
-├─ form/    bound components and useFormStore composition
+├─ input/   DOM value conversion, reset coordination, and element hooks
+├─ form/    standalone and store-bound input components
 ├─ store/   controller and render helpers
 └─ editor/  optional text-editor integration
 

package/dist/index.d.mts

@@ -1,20 +1,11 @@
-import { Immutable, Draft } from 'immer';
-import { Store, EqualityFn } from 'gw-store';
-export * from 'gw-store';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Immutable, Draft } from 'immer';
+import { EqualityFn, Store } from 'gw-store';
 import * as react from 'react';
-import { ReactNode, ChangeEvent, HTMLInputTypeAttribute, RefObject, InputHTMLAttributes, SelectHTMLAttributes, TextareaHTMLAttributes } from 'react';
+import { ReactNode, ChangeEvent, HTMLInputTypeAttribute, RefObject, InputHTMLAttributes, SelectHTMLAttributes, TextareaHTMLAttributes, ReactElement } from 'react';
 import { Result } from 'gw-result';
 export { Result, err, ok } from 'gw-result';
 
-type StoreControllerProps<TState extends object> = {
-    onSubscribe: (state: Immutable<TState>) => void;
-    onDispatch: (state: Draft<TState>) => void;
-};
-declare function useStoreController<TState extends object>(store: Store<TState>, props: StoreControllerProps<TState>): {
-    dispatch: () => void;
-};
-
 type CreateRender<TState extends object> = (selector: (state: Immutable<TState>) => ReactNode, compare?: EqualityFn<Immutable<TState>>) => ReactNode;
 declare function createRender<TState extends object>(store: Store<TState>, selector: (state: Immutable<TState>) => ReactNode, compare?: EqualityFn<Immutable<TState>>): react_jsx_runtime.JSX.Element;
 declare function createRenderWithStore<TState extends object>(store: Store<TState>): CreateRender<TState>;
@@ -59,6 +50,24 @@ declare function assertCodecLaws<TValue, TInput, TError>(codec: Codec<TValue, TI
     equalsInput?: Equality<TInput>;
 }): void;
 
+type StoreBindingMeta<TError> = {
+    valid: true;
+    error?: never;
+} | {
+    valid: false;
+    error: TError;
+};
+type StoreBindingOptions<TValue, TInput> = {
+    onStoreChange?: (input: TInput, value: TValue) => void;
+};
+type StoreBindingResult<TValue, TInput, TError> = {
+    initialValue: TInput;
+    meta: StoreBindingMeta<TError>;
+    commit: (input: TInput) => Result<TValue, TError>;
+    reset: (value: TValue) => void;
+};
+declare function useStoreBinding<TState extends object, TValue, TInput, TError>(store: Store<TState>, binding: InputBinding<TState, TValue, TInput, TError>, options?: StoreBindingOptions<TValue, TInput>): StoreBindingResult<TValue, TInput, TError>;
+
 type InputDisplayValue = string | number | readonly string[];
 type InputStateValue = string | string[];
 type InputControlValue = string | readonly string[] | number | boolean | FileList | null;
@@ -79,20 +88,14 @@ type StoreInputDomProps<TInputElement> = {
     defaultChecked?: boolean;
     onChange: (event: ChangeEvent<TInputElement>) => void;
 };
-type StoreInputMeta<TError> = {
-    valid: true;
-    error?: never;
-} | {
-    valid: false;
-    error: TError;
-};
+type StoreInputMeta<TError> = StoreBindingMeta<TError>;
 type BindingInputResult<TInputElement, TError> = {
     inputProps: StoreInputDomProps<TInputElement>;
     meta: StoreInputMeta<TError>;
 };
 
 type StoreElement$2 = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
-declare function useStoreInput<TInputElement extends StoreElement$2, TState extends object, TValue, TInput extends InputControlValue, TError>(ref: RefObject<TInputElement | null>, store: Store<TState>, binding: InputBinding<TState, TValue, TInput, TError>, options?: StoreInputBindingOptions<TInputElement, TValue>): BindingInputResult<TInputElement, TError>;
+declare function useStoreHTMLElement<TInputElement extends StoreElement$2, TState extends object, TValue, TInput extends InputControlValue, TError>(ref: RefObject<TInputElement | null>, store: Store<TState>, binding: InputBinding<TState, TValue, TInput, TError>, options?: StoreInputBindingOptions<TInputElement, TValue>): BindingInputResult<TInputElement, TError>;
 
 type StoreElement$1 = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
 type StoreInputWithNameProps<TInputElement, TState extends object, TName extends keyof TState> = StoreInputOptions<TInputElement> & {
@@ -111,18 +114,14 @@ type StoreInputWithNameComponentProps<TElement extends StoreElement, TState exte
 type StoreComponentPropsWithStore<TElement extends StoreElement, TState extends object, TName extends keyof TState> = StoreInputWithNameComponentProps<TElement, TState, TName> & {
     store: Store<TState>;
 };
+type StoreComponents<TState extends object> = {
+    input: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLInputElement, TState, TName>) => ReactElement | null;
+    select: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLSelectElement, TState, TName>) => ReactElement | null;
+    textarea: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLTextAreaElement, TState, TName>) => ReactElement | null;
+};
 declare function Input<TState extends object, TName extends keyof TState>({ store, ...props }: StoreComponentPropsWithStore<HTMLInputElement, TState, TName>): react_jsx_runtime.JSX.Element;
 declare function Select<TState extends object, TName extends keyof TState>({ store, ...props }: StoreComponentPropsWithStore<HTMLSelectElement, TState, TName>): react_jsx_runtime.JSX.Element;
 declare function Textarea<TState extends object, TName extends keyof TState>({ store, ...props }: StoreComponentPropsWithStore<HTMLTextAreaElement, TState, TName>): react_jsx_runtime.JSX.Element;
-declare function useStoreComponent<TState extends object>(store: Store<TState>): {
-    input: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLInputElement, TState, TName>) => react_jsx_runtime.JSX.Element;
-    select: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLSelectElement, TState, TName>) => react_jsx_runtime.JSX.Element;
-    textarea: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLTextAreaElement, TState, TName>) => react_jsx_runtime.JSX.Element;
-};
-
-type FormStore<TState extends object> = Store<TState> & ReturnType<typeof useStoreComponent<TState>> & {
-    render: CreateRender<TState>;
-};
-declare function useFormStore<TState extends object>(initialState: TState): FormStore<TState>;
+declare function useStoreInput<TState extends object>(store: Store<TState>): StoreComponents<TState>;
 
-export { type BindingInputResult, type Codec, type CreateRender, type FormStore, Input, type InputBinding, type InputControlValue, type InputDisplayValue, type InputStateValue, type Lens, type LensBuilder, Select, type StateLens, type StoreComponentPropsWithStore, type StoreControllerProps, type StoreInputBindingOptions, type StoreInputDomProps, type StoreInputMeta, type StoreInputOptions, type StoreInputWithNameComponentProps, type StoreInputWithNameProps, Textarea, assertCodecLaws, assertLensLaws, createRender, createRenderWithStore, defineBinding, defineCodec, defineLens, stateLens, useFormStore, useStoreComponent, useStoreController, useStoreInput, useStoreInputWithName };
+export { type BindingInputResult, type Codec, type CreateRender, Input, type InputBinding, type InputControlValue, type InputDisplayValue, type InputStateValue, type Lens, type LensBuilder, Select, type StateLens, type StoreBindingMeta, type StoreBindingOptions, type StoreBindingResult, type StoreComponentPropsWithStore, type StoreComponents, type StoreInputBindingOptions, type StoreInputDomProps, type StoreInputMeta, type StoreInputOptions, type StoreInputWithNameComponentProps, type StoreInputWithNameProps, Textarea, assertCodecLaws, assertLensLaws, createRender, createRenderWithStore, defineBinding, defineCodec, defineLens, stateLens, useStoreBinding, useStoreHTMLElement, useStoreInput, useStoreInputWithName };

package/dist/index.d.ts

@@ -1,20 +1,11 @@
-import { Immutable, Draft } from 'immer';
-import { Store, EqualityFn } from 'gw-store';
-export * from 'gw-store';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Immutable, Draft } from 'immer';
+import { EqualityFn, Store } from 'gw-store';
 import * as react from 'react';
-import { ReactNode, ChangeEvent, HTMLInputTypeAttribute, RefObject, InputHTMLAttributes, SelectHTMLAttributes, TextareaHTMLAttributes } from 'react';
+import { ReactNode, ChangeEvent, HTMLInputTypeAttribute, RefObject, InputHTMLAttributes, SelectHTMLAttributes, TextareaHTMLAttributes, ReactElement } from 'react';
 import { Result } from 'gw-result';
 export { Result, err, ok } from 'gw-result';
 
-type StoreControllerProps<TState extends object> = {
-    onSubscribe: (state: Immutable<TState>) => void;
-    onDispatch: (state: Draft<TState>) => void;
-};
-declare function useStoreController<TState extends object>(store: Store<TState>, props: StoreControllerProps<TState>): {
-    dispatch: () => void;
-};
-
 type CreateRender<TState extends object> = (selector: (state: Immutable<TState>) => ReactNode, compare?: EqualityFn<Immutable<TState>>) => ReactNode;
 declare function createRender<TState extends object>(store: Store<TState>, selector: (state: Immutable<TState>) => ReactNode, compare?: EqualityFn<Immutable<TState>>): react_jsx_runtime.JSX.Element;
 declare function createRenderWithStore<TState extends object>(store: Store<TState>): CreateRender<TState>;
@@ -59,6 +50,24 @@ declare function assertCodecLaws<TValue, TInput, TError>(codec: Codec<TValue, TI
     equalsInput?: Equality<TInput>;
 }): void;
 
+type StoreBindingMeta<TError> = {
+    valid: true;
+    error?: never;
+} | {
+    valid: false;
+    error: TError;
+};
+type StoreBindingOptions<TValue, TInput> = {
+    onStoreChange?: (input: TInput, value: TValue) => void;
+};
+type StoreBindingResult<TValue, TInput, TError> = {
+    initialValue: TInput;
+    meta: StoreBindingMeta<TError>;
+    commit: (input: TInput) => Result<TValue, TError>;
+    reset: (value: TValue) => void;
+};
+declare function useStoreBinding<TState extends object, TValue, TInput, TError>(store: Store<TState>, binding: InputBinding<TState, TValue, TInput, TError>, options?: StoreBindingOptions<TValue, TInput>): StoreBindingResult<TValue, TInput, TError>;
+
 type InputDisplayValue = string | number | readonly string[];
 type InputStateValue = string | string[];
 type InputControlValue = string | readonly string[] | number | boolean | FileList | null;
@@ -79,20 +88,14 @@ type StoreInputDomProps<TInputElement> = {
     defaultChecked?: boolean;
     onChange: (event: ChangeEvent<TInputElement>) => void;
 };
-type StoreInputMeta<TError> = {
-    valid: true;
-    error?: never;
-} | {
-    valid: false;
-    error: TError;
-};
+type StoreInputMeta<TError> = StoreBindingMeta<TError>;
 type BindingInputResult<TInputElement, TError> = {
     inputProps: StoreInputDomProps<TInputElement>;
     meta: StoreInputMeta<TError>;
 };
 
 type StoreElement$2 = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
-declare function useStoreInput<TInputElement extends StoreElement$2, TState extends object, TValue, TInput extends InputControlValue, TError>(ref: RefObject<TInputElement | null>, store: Store<TState>, binding: InputBinding<TState, TValue, TInput, TError>, options?: StoreInputBindingOptions<TInputElement, TValue>): BindingInputResult<TInputElement, TError>;
+declare function useStoreHTMLElement<TInputElement extends StoreElement$2, TState extends object, TValue, TInput extends InputControlValue, TError>(ref: RefObject<TInputElement | null>, store: Store<TState>, binding: InputBinding<TState, TValue, TInput, TError>, options?: StoreInputBindingOptions<TInputElement, TValue>): BindingInputResult<TInputElement, TError>;
 
 type StoreElement$1 = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
 type StoreInputWithNameProps<TInputElement, TState extends object, TName extends keyof TState> = StoreInputOptions<TInputElement> & {
@@ -111,18 +114,14 @@ type StoreInputWithNameComponentProps<TElement extends StoreElement, TState exte
 type StoreComponentPropsWithStore<TElement extends StoreElement, TState extends object, TName extends keyof TState> = StoreInputWithNameComponentProps<TElement, TState, TName> & {
     store: Store<TState>;
 };
+type StoreComponents<TState extends object> = {
+    input: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLInputElement, TState, TName>) => ReactElement | null;
+    select: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLSelectElement, TState, TName>) => ReactElement | null;
+    textarea: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLTextAreaElement, TState, TName>) => ReactElement | null;
+};
 declare function Input<TState extends object, TName extends keyof TState>({ store, ...props }: StoreComponentPropsWithStore<HTMLInputElement, TState, TName>): react_jsx_runtime.JSX.Element;
 declare function Select<TState extends object, TName extends keyof TState>({ store, ...props }: StoreComponentPropsWithStore<HTMLSelectElement, TState, TName>): react_jsx_runtime.JSX.Element;
 declare function Textarea<TState extends object, TName extends keyof TState>({ store, ...props }: StoreComponentPropsWithStore<HTMLTextAreaElement, TState, TName>): react_jsx_runtime.JSX.Element;
-declare function useStoreComponent<TState extends object>(store: Store<TState>): {
-    input: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLInputElement, TState, TName>) => react_jsx_runtime.JSX.Element;
-    select: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLSelectElement, TState, TName>) => react_jsx_runtime.JSX.Element;
-    textarea: <TName extends keyof TState>(props: StoreInputWithNameComponentProps<HTMLTextAreaElement, TState, TName>) => react_jsx_runtime.JSX.Element;
-};
-
-type FormStore<TState extends object> = Store<TState> & ReturnType<typeof useStoreComponent<TState>> & {
-    render: CreateRender<TState>;
-};
-declare function useFormStore<TState extends object>(initialState: TState): FormStore<TState>;
+declare function useStoreInput<TState extends object>(store: Store<TState>): StoreComponents<TState>;
 
-export { type BindingInputResult, type Codec, type CreateRender, type FormStore, Input, type InputBinding, type InputControlValue, type InputDisplayValue, type InputStateValue, type Lens, type LensBuilder, Select, type StateLens, type StoreComponentPropsWithStore, type StoreControllerProps, type StoreInputBindingOptions, type StoreInputDomProps, type StoreInputMeta, type StoreInputOptions, type StoreInputWithNameComponentProps, type StoreInputWithNameProps, Textarea, assertCodecLaws, assertLensLaws, createRender, createRenderWithStore, defineBinding, defineCodec, defineLens, stateLens, useFormStore, useStoreComponent, useStoreController, useStoreInput, useStoreInputWithName };
+export { type BindingInputResult, type Codec, type CreateRender, Input, type InputBinding, type InputControlValue, type InputDisplayValue, type InputStateValue, type Lens, type LensBuilder, Select, type StateLens, type StoreBindingMeta, type StoreBindingOptions, type StoreBindingResult, type StoreComponentPropsWithStore, type StoreComponents, type StoreInputBindingOptions, type StoreInputDomProps, type StoreInputMeta, type StoreInputOptions, type StoreInputWithNameComponentProps, type StoreInputWithNameProps, Textarea, assertCodecLaws, assertLensLaws, createRender, createRenderWithStore, defineBinding, defineCodec, defineLens, stateLens, useStoreBinding, useStoreHTMLElement, useStoreInput, useStoreInputWithName };