@khanglvm/react 1.2.0

package/docs/helpers.md

@@ -0,0 +1,127 @@
+# Helpers and utility types
+
+[Back to the README](../README.md)
+
+Import these through `@khanglvm/react/helpers`; they are not exported from the package root.
+
+## Copying, comparison, and caching
+
+### deepClone(value, cache?)
+
+Use this when copying a nested value with the same rules used by the state utility. It handles cycles, arrays, plain objects, Date, RegExp, Map, Set, and ArrayBuffer. Functions, AbortSignal, and FormData are retained by reference. An optional WeakMap tracks copies during recursion.
+
+```ts
+import { deepClone } from '@khanglvm/react/helpers'
+
+const original = { tags: ['react'], createdAt: new Date('2026-01-01') }
+const copy = deepClone(original)
+copy.tags.push('typescript') // original.tags is unchanged
+```
+
+An object spread only copies one level; this function descends into nested data. For standard structured-clone-compatible data, consider the platform's `structuredClone` first. This helper is not a universal clone: it drops custom object prototypes and symbol properties, and typed-array views are rebuilt from their entire backing buffer without preserving their original offset or length. It also expects AbortSignal and FormData globals to exist.
+
+### deepEqual(a, b)
+
+Use this for value comparison of acyclic objects, arrays, Maps, and Sets when reference equality is insufficient. It also compares Date timestamps, RegExp strings, constructors, and NaN; React element `_owner` fields are skipped.
+
+```ts
+import { deepEqual } from '@khanglvm/react/helpers'
+
+deepEqual({ tags: ['react'] }, { tags: ['react'] }) // true
+```
+
+Maps compare their size, keys, and values. Keys use native Map identity, and values are compared recursively. Sets compare size and membership using native Set identity. Insertion order does not matter. Object keys and Set members must be the same references; matching object contents alone are insufficient.
+
+There is no cycle detection. Symbol and non-enumerable properties are not included. Use a comparator designed for those cases when they are part of your data.
+
+### createCacheStorage(id?)
+
+Use this to retain the previous reference for an equivalent value, keyed by a cache entry and optional group path. Unlike a one-time memoized calculation, callers provide the newly computed value; the cache compares it with the previous one.
+
+```ts
+import { createCacheStorage } from '@khanglvm/react/helpers'
+
+const { cache, clear, uid } = createCacheStorage()
+const group = uid()
+const first = cache({ count: 1 }, 'summary', group)
+const second = cache({ count: 1 }, 'summary', group)
+console.log(first === second) // true
+clear(group)
+```
+
+`cache(value, entryId, ...groupKeys)` returns the earlier value when `deepEqual` says they match. `clear(...groupKeys)` removes a group path; `uid()` returns a new symbol. All equality limitations above apply.
+
+There is no whole-cache clear: `clear()` with no keys does nothing. Supplying a factory ID fixes the entry ID, but its bound `clear()` does not reliably remove the resulting entry. Prefer the unbound factory with explicit groups, as above, and clear groups when their owner is done. Skip this helper when a stable reference or React `useMemo` already solves the problem.
+
+## Memo comparison
+
+`comparePropsForMemo(keys)` builds a comparator for named props. `compareAllPropsForMemo(previous, next)` compares the keys present in the previous props object. Both use `deepEqual`.
+
+```tsx
+import { memo } from 'react'
+import { comparePropsForMemo } from '@khanglvm/react/helpers'
+
+type LabelProps = { label: string }
+export const Label = memo(
+  function Label({ label }: LabelProps) { return <span>{label}</span> },
+  comparePropsForMemo<LabelProps>('label'),
+)
+```
+
+For all existing keys, `memo(Component, compareAllPropsForMemo)` is the companion shorthand; note the added-prop limitation below.
+
+These save writing a custom comparator when bounded nested props need value comparison. Default `memo` is usually the simpler starting point. Include every prop that affects output or behavior, including callbacks; an ignored callback can retain stale data. `compareAllPropsForMemo` can miss a newly added prop because it only visits the previous keys. Both follow the collection identity rules of `deepEqual` and do not support cyclic values.
+
+React's [memo documentation](https://react.dev/reference/react/memo#specifying-a-custom-comparison-function) explains custom comparator costs and the need to compare function props. These helpers do not promise a faster render.
+
+## Children
+
+The child helpers package repeated checks into named functions. Use them only when their exact rules match your component; most components can simply render `children`.
+
+```tsx
+import {
+  isEmptyChildren,
+  isPrimitiveChildren,
+  isReactFragmentChildren,
+  filterComponentFromChildren,
+} from '@khanglvm/react/helpers'
+
+isEmptyChildren(null) // true
+isPrimitiveChildren('Hello') // true
+isReactFragmentChildren(<>Hello</>) // true
+
+function Tab({ title }: { title: string }) { return <span>{title}</span> }
+const tabs = filterComponentFromChildren(
+  [<Tab key="a" title="Overview" />, <span key="b">Other</span>],
+  Tab,
+) // only the Tab element
+```
+
+| Helper | Useful check | Exact behavior and limit |
+| --- | --- | --- |
+| `isIterableChildren(children)` | More than one child slot | Checks `Children.count > 1`; a one-item array returns false. The name does not mean general JavaScript iterability. |
+| `isSingleReactElementChildren(child)` | One non-primitive child slot | Excludes strings, numbers, booleans, null, and undefined. It does not call `isValidElement`; a one-item array can pass. Use React `isValidElement` for element validation. |
+| `isReactFragmentChildren(child)` | A fragment wrapper | Adds a fragment-type string check to the single-child check. It does not inspect the fragment's contents. |
+| `isHTMLElementChildren(child)` | A single non-fragment child | Also accepts custom React components; it does not prove a host HTML element. For that, check `isValidElement(child) && typeof child.type === 'string'`. |
+| `isEmptyChildren(children)` | Absent value | True only for null or undefined; false, an empty string, and an empty array do not pass. |
+| `isPrimitiveChildren(children)` | Text, number, or boolean | Booleans pass even though React does not render them as visible text. |
+| `filterComponentFromChildren(children, Component)` | Direct children of a chosen component type | Uses `Children.toArray`, filters valid elements, and checks exact `child.type` identity. It does not search inside fragments or rendered components. |
+
+React documents these traversal boundaries in [Children](https://react.dev/reference/react/Children#caveats). These predicates are convenience checks, not validators for all ReactNode shapes.
+
+## Types
+
+These exports affect TypeScript only. Use them to reduce repeated type expressions; they do not validate or change runtime values.
+
+| Type | Use and example | Limit |
+| --- | --- | --- |
+| `TAssertFunction<T>` | A generic identity signature preserving a subtype: `TAssertFunction<{ id: string }>` | Declares a function type, not an assertion implementation |
+| `MapKeyType<T>` | Extract a Map key: `MapKeyType<Map<string, number>>` is string | Non-Map inputs resolve to never |
+| `MapValueType<T>` | Extract a Map value: `MapValueType<Map<string, number>>` is number | Non-Map inputs resolve to never |
+| `ExtractValue<T, V>` | Retain a constrained member: `ExtractValue<'a' \| 'b', 'a'>` is 'a' | Returns V; it is not the built-in Extract filter |
+| `TDeepReadonly<T>` | Recursive readonly object/array view: `TDeepReadonly<{ tags: string[] }>` | No runtime freeze; collection handling omits some methods but does not recursively freeze entries or remove every mutator, such as Set.add |
+| `TDeepMutable<T>` | Remove readonly from nested objects/arrays: `TDeepMutable<Readonly<{ count: number }>>` | Built-ins and collection types are largely preserved |
+| `DistributiveOmit<T, K>` | Apply Omit to each union member: `DistributiveOmit<{ kind: 'a'; x: number } \| { kind: 'b'; y: string }, 'kind'>` | A compile-time union transformation |
+| `Prettify<T>` | Expand an object intersection for easier type inspection: `Prettify<{ a: string } & { b: number }>` | Does not transform values |
+
+Root exports also include `TContextState` and `TStateManager`, return-type aliases for their factories, plus `LocalizedString` and `TranslationNamespace`, described in the [translation guide](utilities.md#translation).

package/docs/state.md

@@ -0,0 +1,169 @@
+# State API
+
+[Back to the README](../README.md)
+
+Use `createContextState` for a form, editor, or other feature whose components share editable state. It packages selector hooks, Immer updates, and optional rollback, so each feature does not need to assemble those pieces itself. Keep local state in `useState` when one component owns it.
+
+React's [`useContext`](https://react.dev/reference/react/useContext) subscribes consumers to the provider value. This utility uses context to locate a store and `useSyncExternalStore` to read selected snapshots. It still notifies all store subscribers, then caches selected values using its own equality function. That is a different subscription mechanism, not a promise that a component never re-renders or that this library is faster than another store.
+
+`createContextState<State>(instanceId?)` creates a provider and its hooks. Use an object type for `State`. If you supply an ID, keep it unique to that state utility; the browser uses it to identify a cached context. Declare the factory call outside component renders.
+
+```tsx
+import { createContextState } from '@khanglvm/react'
+
+type ProfileState = {
+  user: { name: string }
+  saving: boolean
+}
+
+export const {
+  Provider,
+  useContextState: useProfileState,
+  useContextStateValue: useProfileValue,
+  useSetContextState: useSetProfile,
+  useStateSnapshotGetter: useProfileSnapshot,
+  withContextProvider,
+} = createContextState<ProfileState>()
+```
+
+## Provider and initialization
+
+```tsx
+<Provider initialState={{ user: { name: 'Khang' }, saving: false }}>
+  <ProfileEditor />
+</Provider>
+```
+
+`initialState` accepts a partial state, but selectors need their fields to exist. Supply a complete initial value. It seeds the provider; use a setter or prop binding for subsequent changes.
+
+Hooks outside a provider fall back to a dummy context whose setters do nothing. Keep consumers under the matching provider.
+
+## Read and update
+
+Inside a component:
+
+```tsx
+const [name, setState, getSnapshot] = useProfileState(state => state.user.name)
+```
+
+The tuple contains the selected value, a setter, and a snapshot getter. Selectors should be pure: derive their result from state without effects, random values, or timestamps. Treat selected values as read-only even though the returned TypeScript type is mutable. Snapshot equality uses `deepEqual`. It compares Map values and Set membership, using native identity for Map keys and Set members. Cyclic structures are unsupported; see the [helper limits](helpers.md#deepequala-b).
+
+The setter accepts either a partial object or an Immer draft callback:
+
+```tsx
+setState({ saving: true })
+setState(draft => {
+  draft.user.name = 'Khang Le'
+})
+```
+
+A partial object replaces each supplied top-level field. It does not deep-merge nested objects. Use a draft callback for nested edits.
+
+`useProfileValue(selector)` returns just the selected value. `useSetProfile()` returns just the setter and does not create a store subscription. A component can still render when its parent or other React state changes.
+
+`useProfileSnapshot()` returns a getter without subscribing:
+
+```tsx
+const getSnapshot = useProfileSnapshot()
+
+function handleSave() {
+  const name = getSnapshot(state => state.user.name)
+  console.log(name)
+}
+```
+
+Snapshots are references to current state, not editable copies. Use the setter for changes.
+
+## Revert an update
+
+With the default hook settings, the setter records Immer inverse patches and returns a function that applies them:
+
+```tsx
+const revert = setState(draft => {
+  draft.user.name = 'New name'
+})
+
+// If this change needs to be undone:
+revert()
+```
+
+This is a per-update rollback, not a history manager. An inverse patch can overwrite a later change to the same field. Coordinate pending saves before using it for optimistic updates.
+
+Pass `false` to skip patch tracking when rollback is unnecessary:
+
+```tsx
+const setState = useSetProfile(false)
+// Or: useProfileState(state => state.user.name, false)
+```
+
+In that mode the returned revert function does nothing.
+
+## Initialize and bind component props
+
+`withContextProvider` wraps a component and can initialize state from its props. Its type parameter describes component props, not the store.
+
+```tsx
+type ProfileProps = { name: string }
+
+const Profile = withContextProvider<ProfileProps>(
+  function ProfileView() {
+    const name = useProfileValue(state => state.user.name)
+    return <p>{name}</p>
+  },
+  {
+    initialState: props => ({ user: { name: props.name }, saving: false }),
+    bindPropToState: (draft, props) => {
+      draft.user.name = props.name
+    },
+  },
+)
+```
+
+`bindPropToState` uses the experimental `StateSynchronizer` and runs in an effect after the initial render. It can overwrite local edits to the fields it binds.
+
+## Advanced hooks
+
+`useSetPostFlush()` returns a registration function for one callback per provider. That callback receives an Immer draft once per microtask batch, before subscribers are notified. A new registration replaces the previous callback; there is no unregister API. See the [implementation](../src/libs/createContextState.tsx) before using it for derived data.
+
+`withStateProvider` is the deprecated name for `withContextProvider`. The separate `createStateManager` factory keeps legacy aliases: `useState`, `useStateValue`, `useSetState`, `useSnapshot`, and `withProvider`.
+
+### StateSynchronizer directly
+
+Use `StateSynchronizer` when an existing provider needs to receive an external value without wrapping the component in another provider. It applies updates in an effect after mount:
+
+```tsx
+const { StateSynchronizer } = createContextState<{ name: string }>()
+// Render under the Provider returned by this same factory:
+// <StateSynchronizer
+//   data={{ name: externalName }}
+//   updateStateOnDataChanged={(draft, data) => { draft.name = data.name }}
+// />
+```
+
+Prefer an ordinary event-handler setter when the change already comes from a user action; prop synchronization introduces another update path.
+
+### Legacy factory
+
+`createStateManager` is useful while maintaining code that already uses its names. It delegates to the current factory and adds aliases, so it is not a different state engine:
+
+```tsx
+import { createStateManager } from '@khanglvm/react'
+const legacy = createStateManager<{ count: number }>()
+// Inside legacy.Provider: legacy.useState(state => state.count)
+```
+
+## Server rendering
+
+Each Provider creates its own store from `initialState`. Server-side selectors
+read that Provider's store, and their selected snapshots are cached. Reusing a
+factory or `instanceId` shares the Context identity; it does not share live state
+between Providers or server requests.
+
+Pass matching initial values on the server and client for hydration. A mounted
+Provider keeps its store, so changing the `initialState` prop does not reset it.
+Use a setter or prop binding for later updates, or mount a new Provider when you
+want a fresh store. Selector caches are cleared when their hooks unmount.
+
+For Next.js App Router, use the hooks inside a client component boundary. The
+package includes a client directive on its state entrypoint. Check hydration in
+your framework, especially when initial state includes request-specific data.

package/docs/utilities.md

@@ -0,0 +1,130 @@
+# Translation and browser events
+
+[Back to the README](../README.md)
+
+## Translation
+
+Use `createTranslator` when you have language variants in a small dictionary and want to select one or substitute text. It saves repeating language lookups. It does not manage locale detection, plural rules, or date and number formatting; use the platform's `Intl` APIs or a fuller i18n system for those needs.
+
+```ts
+import { createTranslator } from '@khanglvm/react'
+
+const t = createTranslator<'en' | 'vi'>('en')
+const greeting = { en: 'Hello USER_NAME', vi: 'Xin chào USER_NAME' }
+console.log(t(greeting, { USER_NAME: 'Khang' })) // Hello Khang
+```
+
+The translator selects the current language, returns an empty string for a missing value at runtime, and replaces matching text case-insensitively. Replacement keys become regular-expression patterns and can match substrings. Use distinctive plain tokens such as `USER_NAME`; `{name}` is not a special placeholder syntax, and a replacement key of `name` would leave the braces in the result. Do not pass arbitrary user text as a replacement key.
+
+### Typed dictionaries and React hooks
+
+`defineLocale<Languages>()` binds the language union once and returns:
+
+- `assertTranslation(dictionary)`: checks dictionary shape at compile time and returns a readonly type. It does not freeze or validate runtime data.
+- `createTranslator(language)`: the translator above, bound to your language union.
+- `createTranslatorHook({ translation, usePreferredLanguage })`: creates hooks that use your app's language source.
+
+This fits a feature that owns a small dictionary and needs the same keys across its components. The app still owns language selection; the utility does not create a shared language store.
+
+```tsx
+import { createContext, useContext } from 'react'
+import { defineLocale } from '@khanglvm/react'
+
+type Language = 'en' | 'vi'
+const LanguageContext = createContext<Language>('en')
+const locale = defineLocale<Language>()
+const translation = locale.assertTranslation({
+  actions: { save: { en: 'Save', vi: 'Lưu' } },
+  messages: { saved: { en: 'Saved', vi: 'Đã lưu' } },
+})
+
+const { useTranslator, createNamespacedTranslatorHook } =
+  locale.createTranslatorHook({
+    translation,
+    usePreferredLanguage: () => useContext(LanguageContext),
+  })
+
+const useActions = createNamespacedTranslatorHook('actions')
+
+function SaveButton() {
+  const { t, d } = useActions()
+  return <button>{t(d.save)}</button>
+}
+
+export default function App() {
+  return (
+    <LanguageContext.Provider value="vi">
+      <SaveButton />
+    </LanguageContext.Provider>
+  )
+}
+```
+
+Inside a component, `useTranslator()` returns `{ t, d, language }`. Choose the shape of `d` with:
+
+| Call | Dictionary returned |
+| --- | --- |
+| `useTranslator()` | Entire dictionary |
+| `useTranslator('actions')` | The actions namespace directly |
+| `useTranslator(['actions', 'messages'])` | Object containing both namespaces |
+| `useTranslator('actions', 'messages')` | Object containing both namespaces |
+| `useTranslator(dict => dict.actions)` | Your selector's result |
+| `createNamespacedTranslatorHook('actions')` | A reusable hook returning that namespace |
+
+Use a string for one namespace. The current implementation returns the namespace directly for a one-item array, even though its overload declares a keyed object. Selecting namespaces shapes the returned dictionary; it does not dynamically load translation files.
+
+The exported types `LocalizedString<Languages>` and `TranslationNamespace<Languages>` describe one translated value and a recursively nested dictionary, respectively.
+
+## Browser events
+
+Use `createEventMethod` when mounted components need to respond to an action elsewhere, especially when the caller needs an answer. A callback prop is simpler for a direct parent-child relationship. Native event dispatch does not itself collect promises returned by listeners; this utility waits for its listeners and returns their results.
+
+```tsx
+import { createEventMethod } from '@khanglvm/react'
+
+type EditorEvents = {
+  'editor:can-close': (data: { documentId: string }) => boolean
+}
+
+const { useEventListener, emitEvent } = createEventMethod<EditorEvents>()
+
+function EditorGuard() {
+  useEventListener('editor:can-close', ({ documentId }) => {
+    return window.confirm(`Close document ${documentId}?`)
+  })
+  return null
+}
+
+function CloseButton() {
+  async function handleClose() {
+    const answers = await emitEvent('editor:can-close', { documentId: 'draft-1' })
+    if (answers.length > 0 && answers.every(answer => answer === true)) {
+      console.log('The mounted listeners agreed to close')
+    }
+  }
+  return <button onClick={handleClose}>Check before closing</button>
+}
+
+export default function App() {
+  return <><EditorGuard /><CloseButton /></>
+}
+```
+
+`useEventListener(name, handler)` registers after mount and removes the listener on unmount. A data-taking handler receives an optional `AbortSignal` as its second argument; unmount aborts the controller for the latest emission. The caller must pass that signal to any operation it wants to cancel. Earlier overlapping emissions are not all cancelled.
+
+`emitEvent(name, data)` calls listeners concurrently and waits with `Promise.allSettled`. Function-shaped event definitions expose an array of results. A failed listener is logged and contributes `undefined`, even when the declared result type excludes it; validate answers before acting. No listeners means no answers.
+
+For notifications, define an object payload:
+
+```ts
+type Notifications = { 'profile:saved': { id: string } }
+const notifications = createEventMethod<Notifications>()
+// Inside a mounted component:
+// notifications.useEventListener('profile:saved', ({ id }) => console.log(id))
+// Inside a browser event handler:
+// await notifications.emitEvent('profile:saved', { id: '123' })
+```
+
+A `() => Result` event can be emitted without data. Avoid relying on the declared first-argument signal for a no-data listener: the current implementation passes data first and signal second in all cases.
+
+All factories share a browser-global registry keyed by event name, so separate factory calls do not isolate identical names. Prefix names by feature. Emitting requires `window`; this is not a server event bus, a replay log, or a delivery guarantee for components that have not mounted.

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@khanglvm/react",
+  "version": "1.2.0",
+  "description": "React utilities for shared state, typed translations, browser events, and component helpers.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./createContextState": {
+      "types": "./dist/libs/createContextState.d.ts",
+      "import": "./dist/libs/createContextState.js",
+      "default": "./dist/libs/createContextState.js"
+    },
+    "./createStateManager": {
+      "types": "./dist/libs/createStateManager.d.ts",
+      "import": "./dist/libs/createStateManager.js",
+      "default": "./dist/libs/createStateManager.js"
+    },
+    "./createEventMethod": {
+      "types": "./dist/libs/createEventMethod.d.ts",
+      "import": "./dist/libs/createEventMethod.js",
+      "default": "./dist/libs/createEventMethod.js"
+    },
+    "./createTranslator": {
+      "types": "./dist/libs/createTranslator.d.ts",
+      "import": "./dist/libs/createTranslator.js",
+      "default": "./dist/libs/createTranslator.js"
+    },
+    "./helpers": {
+      "types": "./dist/helpers/index.d.ts",
+      "import": "./dist/helpers/index.js",
+      "default": "./dist/helpers/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && vite build",
+    "dev": "vite build --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run test && npm run clean && npm run build && npm run test:package",
+    "test": "node --import tsx --test tests/*.test.tsx",
+    "test:package": "tsc --noEmit --strict --module NodeNext --moduleResolution NodeNext --jsx react-jsx --target ES2020 tests/package-smoke.tsx && node --import tsx tests/package-smoke.tsx"
+  },
+  "keywords": [
+    "react",
+    "hooks",
+    "utilities",
+    "typescript",
+    "state-management",
+    "i18n"
+  ],
+  "author": "Khang Le",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.3.7",
+    "jsdom": "^26.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.3.1",
+    "tsx": "^4.23.13",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khanglvm/react.git"
+  },
+  "homepage": "https://github.com/khanglvm/react#readme",
+  "bugs": {
+    "url": "https://github.com/khanglvm/react/issues"
+  },
+  "dependencies": {
+    "immer": "^10.1.1"
+  }
+}