react-store-input 0.2.5 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+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.4.0] - 2026-07-22
+
+### Added
+
+- Typed `Lens`, `Codec`, and `InputBinding` primitives for custom controls.
+- `stateLens` for generating a getter and setter from one typed state path.
+- `gw-result@0.3.0`-based codec parsing with typed failure metadata from
+  `useStoreInput`.
+- `assertLensLaws` and `assertCodecLaws` helpers for testing mapping and
+  round-trip invariants.
+- Top-level `ok`, `err`, and `Result` re-exports for codec implementations.
+
+### Changed
+
+- Removed the deprecated `getter`, `setter`, `toInputValue`, and
+  `toStateValue` APIs. Nested and converted controls now use bindings.
+- Reimplemented named controls internally with a generated Lens and default
+  Codec while preserving built-in conversion and reset behavior.
+- Expanded the custom currency example to demonstrate validation failures and
+  accessible error feedback.
+
+### Fixed
+
+- Preserved invalid raw control input while unrelated store fields update.
+- Cleared binding parse errors and restored the initial domain value on native
+  form reset.
+
+## [0.3.0] - 2026-07-22
+
+### Added
+
+- Standalone `Input`, `Select`, and `Textarea` components with typed named or
+  custom getter/setter bindings.
+- `useStoreInput`, `useStoreController`, `createRender`, and complete
+  `gw-store` API re-exports.
+- An optional `react-store-input/text-editor` entry point that keeps editor
+  dependencies out of the core bundle.
+- Automatic native form reset synchronization, including batched store
+  notifications and multiple-select, date, checkbox, radio, and file values.
+- Runtime, package-consumer, type, and example build tests.
+- A complete interactive example covering the public components, hooks, and
+  supported input value types.
+
+### Changed
+
+- Updated the store integration to use exactly `gw-store@0.2.0`.
+- Published separate CommonJS and ESM entry points with matching declaration
+  files.
+- Made `gw-react-text-editor` an optional peer dependency.
+- Expanded React peer support to React 18 and 19.
+- Organized package source, examples, styles, and runtime tests by
+  responsibility.
+
+### Fixed
+
+- Prevented bundled duplicate React copies from causing invalid hook calls.
+- Preserved numeric radio values and mapped empty numeric inputs to
+  `undefined`.
+- Stored all selected values from multiple selects and normalized empty file
+  inputs to `null`.
+- Kept rendered JSON synchronized after a native form reset.
+- Reduced reset notifications to one batch and eliminated notifications for
+  semantically unchanged arrays and `Date` values.
+
+## [0.2.6] - 2026-04-28
+
+### Added
+
+- Re-exported the `gw-store` API.
+
+## [0.2.5] - 2026-04-27
+
+### Changed
+
+- Added `gw-store` as a package dependency.
+
+## [0.2.4] - 2026-03-16
+
+### Fixed
+
+- Improved store value comparison behavior.
+
+## [0.2.3] - 2026-03-09
+
+### Changed
+
+- Applied package maintenance updates.
+
+## [0.2.2] - 2026-03-09
+
+### Changed
+
+- Added compatible React 18 type and peer dependency ranges.
+
+## [0.2.1] - 2026-01-21
+
+### Changed
+
+- Updated the JSX runtime configuration.
+
+## [0.2.0] - 2026-01-13
+
+### Fixed
+
+- Corrected forwarded ref behavior.

package/README.md

@@ -1,285 +1,263 @@
 # React Store Input
 
-The goal of this package is to make state management easier when using input elements in React.
+Typed, store-backed form controls for React 18 and 19. The package uses
+[`gw-store`](https://www.npmjs.com/package/gw-store) 0.2.0, so state snapshots
+are immutable and updates are made through Immer recipes.
 
-It eliminates repetitive code required to implement state changes and subscriptions for input elements, and provides a simple interface.
+## Install
 
-At the same time, it allows you to use all the attributes originally provided by the input tag as-is, without needing to learn this package.
-
-## Get Started
+```sh
+npm install react-store-input
+```
 
-This is a simple example of how to use this package.
+## Quick start
 
 ```tsx
-import { useFormStore } from "dn-react-input";
+import { useFormStore } from "react-store-input";
 
-export default function App() {
-  const store = useFormStore({
+export default function LoginForm() {
+  const form = useFormStore({
     email: "",
     password: "",
+    rememberMe: false,
   });
 
-  const submit = async () => {
-    const { email, password } = store.state;
-
-    alert(`Email: ${email}\nPassword: ${password}`);
-  };
-
   return (
     <form
-      onSubmit={(e) => {
-        e.preventDefault();
-        submit();
+      onSubmit={(event) => {
+        event.preventDefault();
+        console.log(form.state);
       }}
     >
-      <store.input name="email" type="email" />
-      <store.input name="password" type="password" />
-      <button type="submit">Submit</button>
+      <form.input name="email" type="email" />
+      <form.input name="password" type="password" />
+      <form.input name="rememberMe" type="checkbox" />
+      <button type="submit">Sign in</button>
     </form>
   );
 }
 ```
 
-## How to define state?
+`useFormStore` returns the complete `gw-store` API (`state`, `dispatch`,
+`batch`, and `subscribe`) together with stable `input`, `select`, `textarea`,
+and `render` helpers.
+
+## Components
 
-You can define any state you want as an object when calling `useStore`.
+You can use the standalone components when the store is passed from elsewhere:
 
 ```tsx
-function Component() {
-    ...
+import { Input, Select, Textarea, useStore } from "react-store-input";
 
-    const store = useStore({
-        email: "",
-        password: "",
-        rememberMe: false,
-    });
+const store = useStore({ role: "user", bio: "" });
 
-    ...
-}
+<Input store={store} name="role" type="radio" value="admin" />;
+<Input store={store} name="role" type="radio" value="user" />;
+<Select store={store} name="role">
+  <option value="admin">Admin</option>
+  <option value="user">User</option>
+</Select>;
+<Textarea store={store} name="bio" rows={5} />;
 ```
 
-It's a single source of truth for your form state.
+A named `Input`, `Select`, or `Textarea` requires a valid top-level state key.
+Use `useStoreInput` with a typed binding for nested or converted values.
 
-## How to get input values?
+## Value conversion
 
-You can access the current values of the input elements through the `state` property of the store.
+The default conversions are:
 
-```tsx
-function Component() {
-    ...
+- checkbox → `boolean`
+- radio → the original `value` prop, preserving numbers and strings
+- number/range → `number`, or `undefined` when empty
+- datetime-local → `Date`, or `undefined` when empty or invalid
+- multiple select → `string[]`
+- file → `FileList | null`
+- other controls → `string`
 
-    const submit = () => {
-        const { email, password, rememberMe } = store.state;
-    };
+Domain-specific conversions use a Codec as described below.
 
-    ...
-}
-```
+The controls are store-backed uncontrolled inputs. An explicit `value` or
+`checked` prop is respected as an externally controlled value and is not
+overwritten by store subscriptions. Native form reset is synchronized back to
+the store.
 
-## How to add input elements?
+## Lens, codec, and binding
 
-You can add input elements using the `Input` component provided by the store. There are 'Select' and 'Textarea' components as well.
+A custom control is defined from three small pieces:
 
-```tsx
-import { Input } from "dn-react-input";
-
-function Component() {
-    ...
-
-    return (
-        <form>
-            <Input store={store} name="email" type="email" />
-            <Input store={store} name="password" type="password" />
-            <Input store={store} name="rememberMe" type="checkbox" />
-        </form>
-    );
-}
-```
+- A `Lens<TState, TValue>` selects and updates one domain value in the store.
+- A `Codec<TValue, TInput, TError>` formats that domain value for the control
+  and parses input back to a `gw-result` `Result`.
+- An `InputBinding` combines a lens and codec whose `TValue` types must match.
 
-If you want to avoid passing the store to each input component, use `useStoreComponent`. This hook provides input components that are already connected to the store.
+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.
 
 ```tsx
-import { useStoreComponent } from "dn-react-input";
-
-function Component() {
-    ...
-    const component = useStoreComponent(store);
-
-    return (
-        <form>
-            <component.input name="email" type="email" />
-            <component.input name="password" type="password" />
-            <component.input name="rememberMe" type="checkbox" />
-        </form>
-    );
-}
+import {
+  defineBinding,
+  defineCodec,
+  err,
+  ok,
+  stateLens,
+} from "react-store-input";
+
+type FormState = { profile: { budget?: number } };
+type BudgetError = { code: "INVALID_BUDGET"; input: string };
+
+const budgetBinding = defineBinding({
+  lens: stateLens<FormState>().prop("profile").prop("budget"),
+  codec: defineCodec<number | undefined, string, BudgetError>({
+    format: (value) => value?.toString() ?? "",
+    parse: (input) => {
+      if (input === "") return ok(undefined);
+
+      const value = Number(input);
+      return Number.isFinite(value)
+        ? ok(value)
+        : err({ code: "INVALID_BUDGET", input });
+    },
+  }),
+});
 ```
 
-`useFormStore` is a facade that combines `useStore` and `useStoreInput` for convenience.
+`stateLens().prop(...)` creates `get` and `set` from the same typed path, so
+they cannot accidentally target different fields. `defineLens` is also
+available for computed or otherwise non-path mappings.
 
-```tsx
-import { useFormStore } from "dn-react-input";
-
-function Component() {
-    ...
-    const store = useFormStore({
-        email: "",
-        password: "",
-        rememberMe: false,
-    });
-
-    return (
-        <form>
-            <store.input name="email" type="email" />
-            <store.input name="password" type="password" />
-            <store.input name="rememberMe" type="checkbox" />
-        </form>
-    );
-}
-```
+`ok`, `err`, and the `Result` type are re-exported from `gw-result@0.3.0` for
+codec implementations.
 
-## How to render components on state changes?
+## Rendering selected state
 
-If you want to render a component only when specific parts of the state change, use the `useSelector` hook.
+`useSelector`, `shallowEqual`, and the rest of `gw-store@0.2.0` are re-exported.
 
 ```tsx
-import { useSelector } from "dn-react-input";
+import { createRender, useSelector } from "react-store-input";
 
-function Component() {
-    ...
-    const email = useSelector(store, (state) => state.email);
+const email = useSelector(store, (state) => state.email);
 
-    return <div>Your email is: {email}</div>;
-}
+return (
+  <>
+    <p>{email}</p>
+    {createRender(store, (state) => <p>{state.password.length} characters</p>)}
+    {form.render((state) => <p>{state.rememberMe ? "Remember" : "Forget"}</p>)}
+  </>
+);
 ```
 
-If you want to render components in an inline manner, use the `createRender` function. By using this, you can avoid creating separate components for each part of the state you want to track.
+## Custom controls
 
-```tsx
-import { createRender } from "dn-react-input";
-
-function Component() {
-    ...
-    return (
-        <div>
-            {createRender(store, (state) => <p>{state.email}</p>)}
-            {createRender(store, (state) => <p>{state.password}</p>)}
-        </div>
-    );
-}
-```
-
-`Store.render` is a shortcut for `createRender` when you use `useFormStore`.
+Use `useStoreInput` 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
-function Component() {
-  const store = useFormStore({
-    email: "",
-    password: "",
-  });
+import { useRef } from "react";
+import { useStoreInput, type Store } from "react-store-input";
+
+function BudgetInput({ store }: { store: Store<FormState> }) {
+  const ref = useRef<HTMLInputElement>(null);
+  const field = useStoreInput(ref, store, budgetBinding, { type: "text" });
 
   return (
-    <div>
-      {store.render((state) => (
-        <p>{state.email}</p>
-      ))}
-      {store.render((state) => (
-        <p>{state.password}</p>
-      ))}
-    </div>
+    <label>
+      Budget
+      <input
+        ref={ref}
+        type="text"
+        inputMode="decimal"
+        aria-invalid={!field.meta.valid}
+        {...field.inputProps}
+      />
+      {!field.meta.valid && <span>{field.meta.error.code}</span>}
+    </label>
   );
 }
 ```
 
-## How to subscribe to state changes?
+Generated lenses and codecs can be checked with the exported law assertions in
+unit tests:
 
-You can subscribe to state changes using the `subscribe` method of the store.
+```ts
+assertLensLaws(budgetBinding.lens, {
+  state: { profile: { budget: 10 } },
+  values: [undefined, 0, 25],
+});
 
-```tsx
-function Component() {
-    ...
-    useEffect(() => {
-        const unsubscribe = store.subscribe((state) => {
-            console.log(`State changed`, state);
-        });
-
-        return () => {
-            unsubscribe();
-        };
-    }, []);
-
-    ...
-}
+assertCodecLaws(budgetBinding.codec, {
+  values: [undefined, 0, 25],
+  inputs: ["", "0", "25"],
+});
 ```
 
-## How to update state manually?
+The lens assertions verify get-after-set, set-current-value, and last-set-wins.
+The codec assertion verifies `parse(format(value))` for representative domain
+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.
 
-You can update the state manually using the `dispatch` method of the store.
+For non-input controllers, call the returned `dispatch` when the controller
+changes:
 
 ```tsx
-function Component() {
-    ...
-    const updateEmail = () => {
-        store.dispatch({ email: "ohjinsu98@icloud.com" });
-    };
+import { useStoreController } from "react-store-input";
 
-    return <button onClick={updateEmail}>Update Email</button>;
+function Counter({ store }: { store: Store<{ count: number }> }) {
+  const { dispatch } = useStoreController(store, {
+    onSubscribe: () => {},
+    onDispatch: (state) => {
+      state.count += 1;
+    },
+  });
+
+  return <button onClick={dispatch}>Increment</button>;
 }
 ```
 
-The `dispatch` method uses immerjs internally to update the state, so you can also use a function to update the state based on the previous state.
+## Optional text editor
 
-```tsx
-function Component() {
-    ...
+The ProseMirror-based editor is a separate entry point so normal forms do not
+download or bundle editor dependencies. It requires React 19 and an explicit
+optional peer installation:
 
-    const updateEmail = () => {
-        store.dispatch((state) => {
-            state.email = "ohjinsu98@icloud.com";
-        });
-    };
-
-    return <button onClick={updateEmail}>Update Email</button>;
-}
+```sh
+npm install gw-react-text-editor
 ```
 
-## How to create custom input components?
-
-You can create custom input components using the `useStoreInput` hook. This hook provides the necessary props to connect your custom input component to the store: `name`, `value`, `defaultValue`, `defaultChecked`, `onChange`, and `ref` which already subscribed to the store.
-
 ```tsx
-import { useStoreInput } from "dn-react-input";
-
-function CustomInput({ store }: { store: Store<{ email: string }> }) {
-  const inputProps = useStoreInput(store, {
-    name: "email",
-  });
+import { TextEditor } from "react-store-input/text-editor";
 
-  return <input {...inputProps} />;
-}
+<TextEditor store={store} name="content" />;
 ```
 
-## How to creatre custom controller components?
+## Development
 
-If your custom component is not an html input element, you can use the `useStoreController` hook. This hook provides the necessary props to connect your custom controller component to the store: `ref`, `onSubscribe`, and `onDispatch`.
+Release history is tracked in [CHANGELOG.md](./CHANGELOG.md). The manual
+pre-release checks are documented in [docs/PUBLISHING.md](./docs/PUBLISHING.md).
 
-```tsx
-import { useStoreController } from "dn-react-input";
+Source code is grouped by responsibility:
 
-type State = {
-  count: number;
-};
+```text
+src/
+├─ binding/ Lens, Codec, Binding, and law assertions
+├─ input/   DOM value conversion, reset coordination, and input hooks
+├─ form/    bound components and useFormStore composition
+├─ store/   controller and render helpers
+└─ editor/  optional text-editor integration
 
-function CustomController({ store }: { store: Store<State> }) {
-  const controllerProps = useStoreController<HTMLDivElement, State>(store, {
-    onSubscribe: (state, element) => {
-      element.textContent = `Count: ${state.count}`;
-    },
-    onDispatch: (state, element) => {
-      state.count += Number(element.textContent.replace("Count: ", ""));
-    },
-  });
+example/src/
+├─ components/  reusable demo UI
+├─ sections/    one catalog section per capability group
+├─ demo/        state model and initial data
+└─ styles/      layout, fields, toolbar, state panel, and responsive rules
+```
 
-  return <div {...controllerProps} />;
-}
+```sh
+npm run typecheck
+npm test
+npm pack --dry-run
 ```