@khanglvm/react 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khang Le
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# @khanglvm/react
+
+React utilities for shared state, translation, and browser events, with helpers for component props and children.
+
+I built these to reuse the setup that kept appearing in my React work. `createContextState` is the main state utility: one factory gives you typed selector hooks, Immer draft updates, and a revert function for each update. The other tools work independently.
+
+## Choose a tool
+
+| When you need to… | Start here | What it adds |
+| --- | --- | --- |
+| Share editable state across components | [createContextState](https://github.com/khanglvm/react/blob/master/docs/state.md) | Selectors, draft updates, and per-update rollback in one API |
+| Keep translation keys and language variants together | [defineLocale / createTranslator](https://github.com/khanglvm/react/blob/master/docs/utilities.md#translation) | Typed dictionaries, namespace hooks, and text substitution |
+| Ask mounted components for an async response | [createEventMethod](https://github.com/khanglvm/react/blob/master/docs/utilities.md#browser-events) | Typed event data and collected listener results |
+| Reuse equality, caching, or React child checks | [Helpers](https://github.com/khanglvm/react/blob/master/docs/helpers.md) | Small functions with explicit behavior and limits |
+
+For state owned by one component, `useState` is usually enough. These utilities help when several components share the same work. Read the guides for examples and tradeoffs before choosing one.
+
+## Install
+
+Use React 18 or 19. The package ships ES modules and TypeScript declarations.
+
+```sh
+npm install @khanglvm/react
+```
+
+The [npm package](https://www.npmjs.com/package/@khanglvm/react) includes the
+state utility, translations, browser events, and component helpers. Import
+what you need; the utilities work independently.
+
+## Shared state in one file
+
+Put this in `App.tsx` in a React TypeScript app. In Next.js App Router, add `'use client'` as the first line.
+
+```tsx
+import { createContextState } from '@khanglvm/react'
+
+type CounterState = { count: number }
+
+const {
+  Provider,
+  useContextStateValue: useCounterValue,
+  useSetContextState: useSetCounter,
+} = createContextState<CounterState>()
+
+function CounterValue() {
+  const count = useCounterValue(state => state.count)
+  return <p>Count: {count}</p>
+}
+
+function IncrementButton() {
+  const setState = useSetCounter()
+
+  return (
+    <button onClick={() => setState(draft => { draft.count += 1 })}>
+      Add one
+    </button>
+  )
+}
+
+export default function App() {
+  return (
+    <Provider initialState={{ count: 0 }}>
+      <CounterValue />
+      <IncrementButton />
+    </Provider>
+  )
+}
+```
+
+Create the state utility outside component renders. Initialize every field your selectors read, keep selectors pure, and use the setter to change state. A hook outside its provider cannot update the store.
+
+## More examples
+
+- [State API, reverting updates, and binding props](https://github.com/khanglvm/react/blob/master/docs/state.md)
+- [Translation and browser events](https://github.com/khanglvm/react/blob/master/docs/utilities.md)
+- [Every helper and exported type](https://github.com/khanglvm/react/blob/master/docs/helpers.md)
+- [Implementation](https://github.com/khanglvm/react/blob/master/src/libs/createContextState.tsx)
+
+`createStateManager` remains available for older hook names. Use `createContextState` in new code.
+
+## Using a coding agent
+
+Give your agent the repository URL and a small task:
+
+> Read the README and the guide for the relevant utility in https://github.com/khanglvm/react. Explain whether it fits this feature before adding it. Install `@khanglvm/react` from npm, preserve the documented API, and check the example against my app's React version. For shared state, use typed selectors and Immer draft updates under the matching provider.
+
+By [Khang Le](https://khangle.dev). MIT licensed.

package/dist/helpers/createCacheStorage.d.ts

@@ -0,0 +1,5 @@
+export declare const createCacheStorage: (id?: (symbol | string)) => {
+    cache: <T>(input: T, ...keys: (symbol | string)[]) => T;
+    clear: (...keys: (symbol | string)[]) => void;
+    uid: () => symbol;
+};

package/dist/helpers/createCacheStorage.js

@@ -0,0 +1,35 @@
+import { deepEqual as l } from "./deepEqual.js";
+const M = (c) => {
+  const n = /* @__PURE__ */ new Map();
+  function o(t, e) {
+    return e.length === 0 ? t : (t.has(e[0]) || t.set(e[0], /* @__PURE__ */ new Map()), o(t.get(e[0]), e.slice(1)));
+  }
+  function f(t, e, ...g) {
+    const r = o(n, g);
+    if (r.get(e) === void 0)
+      return r.set(e, t), t;
+    const i = r.get(e);
+    return l(i, t) ? i : (r.set(e, t), t);
+  }
+  function u(t, e) {
+    if (e.length !== 0) {
+      if (e.length === 1) {
+        t.delete(e[0]);
+        return;
+      }
+      if (!(t.get(e[0]) === void 0 || !(t.get(e[0]) instanceof Map)))
+        return u(t.get(e[0]), e.slice(1));
+    }
+  }
+  function a(...t) {
+    u(n, t);
+  }
+  return {
+    cache: typeof c < "u" ? (t, ...e) => f(t, c, ...e) : f,
+    clear: c ? () => a(c) : a,
+    uid: () => Symbol()
+  };
+};
+export {
+  M as createCacheStorage
+};

package/dist/helpers/deepClone.d.ts

@@ -0,0 +1 @@
+export declare function deepClone<T>(value: T, cache?: WeakMap<object, unknown>): T;

package/dist/helpers/deepClone.js

@@ -0,0 +1,53 @@
+function f(t, n = /* @__PURE__ */ new WeakMap()) {
+  const e = Object.prototype.toString.call(t);
+  if (t === null || typeof t != "object")
+    return t;
+  if (n.has(t))
+    return n.get(t);
+  if (t instanceof Date)
+    return new Date(t.getTime());
+  if (t instanceof RegExp)
+    return new RegExp(t.source, t.flags);
+  if (t instanceof AbortSignal || t instanceof FormData)
+    return t;
+  if (t instanceof Map) {
+    const r = /* @__PURE__ */ new Map();
+    return n.set(t, r), t.forEach((o, i) => {
+      r.set(f(i, n), f(o, n));
+    }), r;
+  }
+  if (t instanceof Set) {
+    const r = /* @__PURE__ */ new Set();
+    return n.set(t, r), t.forEach((o) => {
+      r.add(f(o, n));
+    }), r;
+  }
+  if (t instanceof ArrayBuffer)
+    return t.slice(0);
+  if (ArrayBuffer.isView(t)) {
+    if (!(t.buffer instanceof ArrayBuffer))
+      throw new Error(`Unsupported type: ${e}`);
+    const r = new t.constructor(
+      t.buffer.slice(0)
+    );
+    return n.set(t, r), r;
+  }
+  if (Array.isArray(t)) {
+    const r = [];
+    n.set(t, r);
+    for (const o of t)
+      r.push(f(o, n));
+    return r;
+  }
+  if (Object.prototype.toString.call(t) === "[object Object]") {
+    const r = {};
+    n.set(t, r);
+    for (const o in t)
+      Object.prototype.hasOwnProperty.call(t, o) && (r[o] = f(t[o], n));
+    return r;
+  }
+  throw new Error(`Unsupported type: ${e}`);
+}
+export {
+  f as deepClone
+};

package/dist/helpers/deepEqual.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Deep equality comparison with optimizations
+ *
+ * Incorporates performance optimizations from fast-deep-equal
+ * Credit: https://github.com/epoberezkin/fast-deep-equal
+ * Author: Evgeny Poberezkin
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/dist/helpers/deepEqual.js

@@ -0,0 +1,63 @@
+const p = Array.isArray, y = Object.keys, h = Object.prototype.hasOwnProperty;
+function o(t, e) {
+  if (t === e)
+    return !0;
+  if (t && e && typeof t == "object" && typeof e == "object") {
+    const i = p(t), c = p(e);
+    if (i && c) {
+      const r = t.length;
+      if (r !== e.length)
+        return !1;
+      for (let n = r; n-- !== 0; )
+        if (!o(t[n], e[n]))
+          return !1;
+      return !0;
+    }
+    if (i !== c)
+      return !1;
+    const u = t instanceof Date, l = e instanceof Date;
+    if (u !== l)
+      return !1;
+    if (u && l)
+      return t.getTime() === e.getTime();
+    const a = t instanceof RegExp, g = e instanceof RegExp;
+    if (a !== g)
+      return !1;
+    if (a && g)
+      return t.toString() === e.toString();
+    if (t.constructor !== e.constructor)
+      return !1;
+    if (t instanceof Map && e instanceof Map) {
+      if (t.size !== e.size)
+        return !1;
+      for (const [r, n] of t)
+        if (!e.has(r) || !o(n, e.get(r)))
+          return !1;
+      return !0;
+    }
+    if (t instanceof Set && e instanceof Set) {
+      if (t.size !== e.size)
+        return !1;
+      for (const r of t)
+        if (!e.has(r))
+          return !1;
+      return !0;
+    }
+    const f = y(t), s = f.length;
+    if (s !== y(e).length)
+      return !1;
+    for (let r = s; r-- !== 0; )
+      if (!h.call(e, f[r]))
+        return !1;
+    for (let r = s; r-- !== 0; ) {
+      const n = f[r];
+      if (!(n === "_owner" && t.$$typeof) && !o(t[n], e[n]))
+        return !1;
+    }
+    return !0;
+  }
+  return t !== t && e !== e;
+}
+export {
+  o as deepEqual
+};

package/dist/helpers/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Helper utilities and types for @khanglvm/react
+ */
+export * from './types.js';
+export * from './deepClone.js';
+export * from './deepEqual.js';
+export * from './createCacheStorage.js';
+export * from './react.js';

package/dist/helpers/index.js

@@ -0,0 +1,18 @@
+import { deepClone as o } from "./deepClone.js";
+import { deepEqual as l } from "./deepEqual.js";
+import { createCacheStorage as m } from "./createCacheStorage.js";
+import { compareAllPropsForMemo as p, comparePropsForMemo as a, filterComponentFromChildren as C, isEmptyChildren as d, isHTMLElementChildren as h, isIterableChildren as s, isPrimitiveChildren as c, isReactFragmentChildren as f, isSingleReactElementChildren as x } from "./react.js";
+export {
+  p as compareAllPropsForMemo,
+  a as comparePropsForMemo,
+  m as createCacheStorage,
+  o as deepClone,
+  l as deepEqual,
+  C as filterComponentFromChildren,
+  d as isEmptyChildren,
+  h as isHTMLElementChildren,
+  s as isIterableChildren,
+  c as isPrimitiveChildren,
+  f as isReactFragmentChildren,
+  x as isSingleReactElementChildren
+};

package/dist/helpers/react.d.ts

@@ -0,0 +1,26 @@
+import { JSXElementConstructor, ReactNode } from 'react';
+
+/**
+ * Use comparePropsForMemo/ compareAllPropsForMemo function to quickly compare prop(s) for React.memo
+ * Usage example:
+ * memo(Component, compareAllPropsForMemo) // compare all props
+ * memo(Component, comparePropsForMemo('title')) // compare only 'title' prop
+ * memo(Component, comparePropsForMemo(['title', 'content'])) // compare 'title' and 'content' props
+ * */
+type TPropsAreEqualsCallback<P> = (prevProps: P, nextProps: P) => boolean;
+export declare function compareAllPropsForMemo<P extends object>(arg1: P, arg2: P): boolean;
+export declare function comparePropsForMemo<P extends object>(arg: Array<keyof P> | keyof P): TPropsAreEqualsCallback<P>;
+export declare function isIterableChildren<T>(children: T): children is TReactFragment<T>;
+export declare function isSingleReactElementChildren<T>(child: T): child is TReactElement<T>;
+export declare function isReactFragmentChildren<T>(child: T): child is TReactElement<T>;
+export declare function isHTMLElementChildren<T>(child: T): child is TReactElement<T>;
+export declare function isEmptyChildren<T>(children: T): children is TEmptyChildren<T>;
+export declare function isPrimitiveChildren<T>(children: T): children is TPrimitiveChildren<T>;
+type TEmpty = undefined | null | '';
+type TPrimitive = string | number | boolean;
+type TPrimitiveChildren<T> = T extends TPrimitive ? T : never;
+type TEmptyChildren<T> = T extends TEmpty ? T : never;
+type TReactElement<T> = T extends TPrimitiveChildren<T> ? never : T extends TEmptyChildren<T> ? never : T;
+type TReactFragment<T> = T extends Iterable<ReactNode> ? T : never;
+export declare const filterComponentFromChildren: <T extends JSXElementConstructor<any>>(children: ReactNode | ReactNode[], Component: T) => import('react').ReactElement<unknown, string | JSXElementConstructor<any>>[];
+export {};

package/dist/helpers/react.js

@@ -0,0 +1,44 @@
+import { Children as i, isValidElement as f } from "react";
+import { deepEqual as m } from "./deepEqual.js";
+function l(t) {
+  return t.length === 1;
+}
+function c(t, e) {
+  return o(t, e);
+}
+function s(...t) {
+  return l(t) ? (e, n) => o(e, n, Array.isArray(t[0]) ? t[0] : [t[0]]) : o(t[0], t[1]);
+}
+function o(t, e, n) {
+  return !(n || Object.keys(t).filter((r) => Object.prototype.hasOwnProperty.call(t, r))).some((r) => !m(t[r], e[r]));
+}
+function C(t) {
+  return i.count(t) > 1;
+}
+function u(t) {
+  return i.count(t) === 1 && typeof t != "string" && typeof t != "number" && typeof t != "boolean" && t !== void 0 && t !== null;
+}
+function p(t) {
+  return u(t) && t.type !== void 0 && t.type.toString() === Symbol("react.fragment").toString();
+}
+function b(t) {
+  return u(t) && !p(t);
+}
+function g(t) {
+  return t == null;
+}
+function A(t) {
+  return typeof t == "string" || typeof t == "number" || typeof t == "boolean";
+}
+const E = (t, e) => i.toArray(t).filter(f).filter((n) => n.type === e);
+export {
+  c as compareAllPropsForMemo,
+  s as comparePropsForMemo,
+  E as filterComponentFromChildren,
+  g as isEmptyChildren,
+  b as isHTMLElementChildren,
+  C as isIterableChildren,
+  A as isPrimitiveChildren,
+  p as isReactFragmentChildren,
+  u as isSingleReactElementChildren
+};

package/dist/helpers/types.d.ts

@@ -0,0 +1,19 @@
+export type TAssertFunction<T> = <StrongTypedEntity extends T>(assertEntity: StrongTypedEntity) => StrongTypedEntity;
+export type MapValueType<Target> = Target extends Map<unknown, infer Type> ? Type : never;
+export type MapKeyType<Target> = Target extends Map<infer Type, unknown> ? Type : never;
+export type ExtractValue<T, V extends T> = V;
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type FunctionType = (...args: any[]) => any;
+type BuiltInObjects = Date | RegExp | URL | URLSearchParams | Promise<any> | Error;
+type CollectionTypes = Map<any, any> | Set<any> | WeakMap<object, any> | WeakSet<object> | ArrayBuffer | SharedArrayBuffer | Uint8Array | Uint16Array | Uint32Array | Int8Array | Int16Array | Int32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+export type TDeepReadonly<T> = T extends Primitive ? T : T extends FunctionType ? T : T extends CollectionTypes ? Omit<T, "set" | "delete" | "clear" | "push" | "pop" | "shift" | "unshift" | "splice" | "sort" | "reverse" | "fill"> : T extends BuiltInObjects ? T : T extends Array<infer U> ? ReadonlyArray<TDeepReadonly<U>> : T extends {} ? {
+    readonly [K in keyof T]: TDeepReadonly<T[K]>;
+} : Readonly<T>;
+export type TDeepMutable<T> = T extends Primitive ? T : T extends FunctionType ? T : T extends CollectionTypes ? T : T extends BuiltInObjects ? T : T extends ReadonlyArray<infer U> ? Array<TDeepMutable<U>> : T extends {} ? {
+    -readonly [P in keyof T]: TDeepMutable<T[P]>;
+} : T;
+export type DistributiveOmit<T, K extends PropertyKey> = T extends any ? Omit<T, K> : never;
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './libs/createContextState.js';
+export * from './libs/createStateManager.js';
+export * from './libs/createTranslator.js';
+export * from './libs/createEventMethod.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+"use client";
+import { createContextState as r } from "./libs/createContextState.js";
+import { createStateManager as a } from "./libs/createStateManager.js";
+import { createTranslator as n, defineLocale as f } from "./libs/createTranslator.js";
+import { createEventMethod as m } from "./libs/createEventMethod.js";
+export {
+  r as createContextState,
+  m as createEventMethod,
+  a as createStateManager,
+  n as createTranslator,
+  f as defineLocale
+};

package/dist/libs/createContextState.d.ts

@@ -0,0 +1,89 @@
+import { ComponentType, PropsWithChildren, PropsWithoutRef } from 'react';
+import { Draft } from 'immer';
+import { TDeepMutable, TDeepReadonly } from '../helpers/index.js';
+
+/**
+ * Global window interface extension for state persistence across renders
+ * Stores state instances in a Map to prevent recreation on hot reloads
+ */
+declare global {
+    interface Window {
+        __CONTEXT_STATE__: Map<symbol | string, {
+            state: unknown;
+            instance: unknown;
+        }>;
+    }
+}
+/** Function that modifies state using Immer draft pattern */
+type DraftFunction<T> = (draft: Draft<T>) => void;
+/** Function that modifies state using Immer draft pattern with additional data */
+type DraftFunctionWithData<T, D> = (draft: Draft<T>, data: D) => void;
+/**
+ * Brief document of how createContextState works internally:
+ *
+ * 1. **Context Creation**: Creates a React Context that holds state management functions
+ * 2. **State Storage**: Uses different storage strategies for SSR vs client:
+ *    - Server: Fresh state per request
+ *    - Client: Persists in window.__CONTEXT_STATE__ for chunking support
+ * 3. **Subscription System**: Implements external store pattern with useSyncExternalStore
+ * 4. **Immer Integration**: All state updates go through Immer for immutability + patches
+ * 5. **Caching Layer**: Uses createCacheStorage for memoization and performance
+ * 6. **Pure Function Validation**: Validates compute functions to prevent render loops
+ *
+ * Flow: Component → useContextState → useSyncExternalStore → subscribers → re-render
+ * */
+export declare function createContextState<State extends Record<string | number, unknown>>(instanceId?: string): {
+    /** React component to provide state context */
+    Provider: import('react').NamedExoticComponent<PropsWithChildren<{
+        initialState?: Partial<State>;
+    }>>;
+    /** Hook for full state access (read + write + computed values) */
+    useContextState: <ComputedValue = State>(compute?: (state: TDeepReadonly<State>) => ComputedValue, enableRevert?: boolean) => [TDeepMutable<ComputedValue>, <T extends Partial<State> | DraftFunction<State>>(valueOrUpdater: T) => () => void, {
+        <ComputedSnapshotValue>(compute: (input: State) => ComputedSnapshotValue): ComputedSnapshotValue;
+        (compute?: undefined): State;
+    }];
+    /** Hook for read-only state access with computed values */
+    useContextStateValue: <ComputedValue = State>(compute?: (state: TDeepReadonly<State>) => ComputedValue) => TDeepMutable<ComputedValue>;
+    /** Hook for write-only state access */
+    useSetContextState: (enableRevert?: boolean) => <T extends Partial<State> | DraftFunction<State>>(valueOrUpdater: T) => () => void;
+    /** Hook for synchronous state snapshot access */
+    useStateSnapshotGetter: () => {
+        <ComputedSnapshotValue>(compute: (input: State) => ComputedSnapshotValue): ComputedSnapshotValue;
+        (compute?: undefined): State;
+    };
+    /** Hook to register a postFlush callback (runs once per batch before subscribers) */
+    useSetPostFlush: () => (callback: (draft: Draft<State>) => void) => void;
+    /** Component for syncing external props to state */
+    StateSynchronizer: <ComponentProps>({ updateStateOnDataChanged, data }: {
+        data?: ComponentProps;
+        updateStateOnDataChanged?: DraftFunctionWithData<State, ComponentProps>;
+    }) => null;
+    /** @deprecated - renamed to withContextProvider */
+    withStateProvider: <ComponentProps>(WrappedComponent: ComponentType<ComponentProps>, config?: {
+        /**
+         * Transform component props to initial state
+         * Called once when component mounts
+         */
+        initialState?: (props: PropsWithoutRef<ComponentProps>) => Partial<State>;
+        /**
+         * Sync prop changes to state updates
+         * Called whenever props change (except first render)
+         */
+        bindPropToState?: DraftFunctionWithData<State, PropsWithoutRef<ComponentProps>>;
+    }) => import('react').ForwardRefExoticComponent<PropsWithoutRef<ComponentProps> & import('react').RefAttributes<unknown>>;
+    /** HOC to automatically wrap components with state provider */
+    withContextProvider: <ComponentProps>(WrappedComponent: ComponentType<ComponentProps>, config?: {
+        /**
+         * Transform component props to initial state
+         * Called once when component mounts
+         */
+        initialState?: (props: PropsWithoutRef<ComponentProps>) => Partial<State>;
+        /**
+         * Sync prop changes to state updates
+         * Called whenever props change (except first render)
+         */
+        bindPropToState?: DraftFunctionWithData<State, PropsWithoutRef<ComponentProps>>;
+    }) => import('react').ForwardRefExoticComponent<PropsWithoutRef<ComponentProps> & import('react').RefAttributes<unknown>>;
+};
+export type TContextState = ReturnType<typeof createContextState>;
+export {};