state-in-url 2.2.0 → 2.2.1

package/README.md

@@ -20,7 +20,7 @@ English | [한국어](./README.KO.md) | [简体中文](./README.CN.md)
 
 <div align="center">
 
-<h4 align="center">Don't hesitate to open an issue if you found a bug</h4>
+<h4 align="center">Don't hesitate to open an issue if you found a bug, or for requesting features</h4>
 
 ![Demo-gif](https://github.com/asmyshlyaev177/state-in-url/assets/19854148/c9802601-4d42-4362-b3e4-37ff87c3b97f)
 
@@ -50,10 +50,10 @@ Add a ⭐️ to support the project!
 
 # Features
 
-- 🧩 **Simple**: No providers, reducers, boilerplate or new concepts
-- 📘 **Typescript support and type Safety**: Preserves data types and structure, enhances developer experience with IDE suggestions, strong typing and JSDoc comments
+- 🧩 **Simple**: No providers, reducers, boilerplate or new concepts, API similar to React.useState
+- 📘 **Typescript support and type Safety**: Preserves data types and structure, good developer experience with IDE suggestions, strong typing and JSDoc comments
 - ⚛️ **Framework Flexibility**: Separate hooks for Next.js and React.js applications, and functions for pure JS
-- ⚙ **Well tested**: Unit tests and Playwright tests
+- ⚙ **Well tested**: Unit tests and Playwright tests, high quality and support
 - ⚡ **Fast**: Minimal rerenders
 - 🪶 **Lightweight**: Zero dependencies for a smaller footprint
 
@@ -88,7 +88,8 @@ pnpm add state-in-url
 
 ### 2. Edit tsconfig.json
 
-In `tsconfig.json` in `compilerOptions` set `"moduleResolution": "Node16"` or `"moduleResolution": "NodeNext"`
+In `tsconfig.json` in `compilerOptions` set `"moduleResolution": "Bundler"`, or`"moduleResolution": "Node16"`, or `"moduleResolution": "NodeNext"`.
+Possibly need to set `"module": "ES2022"`, or `"module": "ESNext"`
 
 ## useUrlState hook for Next.js
 
@@ -103,11 +104,11 @@ In `tsconfig.json` in `compilerOptions` set `"moduleResolution": "Node16"` or `"
 1. Define state shape
 
    ```typescript
-   // countState.ts
+   // userState.ts
    // State shape should be stored in a constant, don't pass an object directly
-   export const countState: CountState = { count: 0 }
+   export const userState: UserState = { name: '', age: 0 }
 
-   type CountState = { count: number }
+   type UserState = { name: string, age: number }
    ```
 
 2. Import it and use
@@ -116,39 +117,37 @@ In `tsconfig.json` in `compilerOptions` set `"moduleResolution": "Node16"` or `"
 'use client'
 import { useUrlState } from 'state-in-url/next';
 
-import { countState } from './countState';
+import { userState } from './userState';
 
 function MyComponent() {
-  // for use searchParams from server component
-  // e.g. export default async function Home({ searchParams }: { searchParams: object }) {
-  // const { state, updateState, updateUrl } = useUrlState({ defaultState: countState, searchParams });
   // can pass `replace` arg, it's control will `updateUrl` will use `rounter.push` or `router.replace`, default replace=true
-  // const { state, updateState, updateUrl } = useUrlState({ defaultState: countState, searchParams, replace: false });
-  const { state, updateState, updateUrl } = useUrlState({ defaultState: countState });
+  // const { state, updateState, updateUrl } = useUrlState({ defaultState: userState, searchParams, replace: false });
+  const { state, updateState, updateUrl } = useUrlState({ defaultState: userState });
 
   // won't let you to accidently mutate state directly, requires TS
-  // state.count = 2 // <- error
+  // state.name = 'John' // <- error
 
   return (
     <div>
-      <p>Count: {state.count}</p>
-
-      <button onClick={() => updateUrl({ count: state.count + 1 }), { replace: true }}>
-        Increment (Update URL)
-      </button>
-
-        // same api as React.useState
-      <button onClick={() => updateState(currState => ({...currState, count: currState.count + 1 }) )}>
-        Increment (Local Only)
-      </button>
-      <button onClick={() => updateUrl()}>
-        Sync changes to url
-        // Or don't sync it and just share state
-      </button>
-
-      <button onClick={() => updateUrl(state)}>
+      <input value={state.name}
+        onChange={(ev) => { updateState({ name: ev.target.value }) }}
+        onBlur={() => updateUrl()}
+      />
+      <input value={state.age}
+        onChange={(ev) => { updateState({ age: +ev.target.value }) }}
+        onBlur={() => updateUrl()}
+      />
+
+      // same api as React.useState
+      <input value={state.name}
+        onChange={(ev) => { updateState(curr => ({ ...curr, name: ev.target.value })) }}
+        onBlur={() => updateUrl()}
+      />
+
+      <button onClick={() => updateUrl(userState)}>
         Reset
       </button>
+
     </div>
   )
 }
@@ -157,74 +156,80 @@ function MyComponent() {
 #### With complex state shape
 
 ```typescript
-interface UserSettings {
-  theme: 'light' | 'dark';
-  fontSize: number;
-  notifications: boolean;
-}
+export const form: Form = {
+  name: '',
+  age: undefined,
+  'agree to terms': false,
+  tags: [],
+};
+
+type Form = {
+  name: string;
+  age?: number;
+  'agree to terms': boolean;
+  tags: { id: string; value: { text: string; time: Date } }[];
+};
 
-export const userSettings: UserSettings {
-  theme: 'light',
-  fontSize: 16,
-  notifications: true,
-}
 ```
 
 ```typescript
 'use client'
 import { useUrlState } from 'state-in-url/next';
 
-import { userSettings } from './userSettings';
-
-function SettingsComponent() {
-  // `state` will infer from UserSettings type!
-  const { state, updateUrl } = useUrlState({ defaultState: userSettings });
-
-  const toggleTheme = () => {
-    updateUrl(current => ({
-      ...current,
-      theme: current.theme === 'light' ? 'dark' : 'light',
-    }));
-  };
-
-  // sync state to url when idle
-  const timer = React.useRef(0 as unknown as NodeJS.Timeout);
-  React.useEffect(() => {
-    clearTimeout(timer.current);
-    timer.current = setTimeout(() => {
-      // will compare state by content not by reference and fire update only for new values
-      updateUrl(state);
-    }, 500);
+import { form } from './form';
 
-    return () => {
-      clearTimeout(timer.current);
-    };
-  }, [state, updateUrl]);
+function TagsComponent() {
+  // `state` will infer from Form type!
+  const { state, updateUrl } = useUrlState({ defaultState: form });
+
+  const onChangeTags = React.useCallback(
+    (tag: (typeof tags)[number]) => {
+      updateUrl((curr) => ({
+        ...curr,
+        tags: curr.tags.find((t) => t.id === tag.id)
+          ? curr.tags.filter((t) => t.id !== tag.id)
+          : curr.tags.concat(tag),
+      }));
+    },
+    [updateUrl],
+  );
 
   return (
     <div>
-      <h2>User Settings</h2>
-      <p>Theme: {state.theme}</p>
-      <p>Font Size: {state.fontSize}px</p>
-      <button onClick={toggleTheme}>Toggle Theme</button>
-      {/* Other UI elements to update other settings */}
+      <Field text="Tags">
+        <div className="flex flex-wrap gap-2">
+          {tags.map((tag) => (
+            <Tag
+              active={!!state.tags.find((t) => t.id === tag.id)}
+              text={tag.value.text}
+              onClick={() => onChangeTags(tag)}
+              key={tag.id}
+            />
+          ))}
+        </div>
+      </Field>
     </div>
   );
 }
-...
-
-// Other component
-function Component() {
-  const { state } = useUrlState({ defaultState: defaultSettings });
 
-  return (
-    <div>
-      <p>Notifications is {state.notifications ? 'On' : 'Off'}</p>
-    </div>
-  )
-}
+const tags = [
+  {
+    id: '1',
+    value: { text: 'React.js', time: new Date('2024-07-17T04:53:17.000Z') },
+  },
+  {
+    id: '2',
+    value: { text: 'Next.js', time: new Date('2024-07-18T04:53:17.000Z') },
+  },
+  {
+    id: '3',
+    value: { text: 'TailwindCSS', time: new Date('2024-07-19T04:53:17.000Z') },
+  },
+];
 ```
 
+[Demo page example code](https://github.com/asmyshlyaev177/state-in-url/blob/main/packages/example-nextjs/src/app/Form.tsx)
+
 #### Auto sync state
 
 ```typescript

package/dist/useUrlStateBase/useUrlStateBase.mjs

@@ -1 +1 @@
-import t from"react";import{parseSsrQs as e}from"../next/parseSsrQs.mjs";import{useInsertionEffect as n}from"../useInsertionEffect.mjs";import{useSharedState as o}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as r}from"../useUrlEncode/useUrlEncode.mjs";import{isSSR as s}from"../utils.mjs";function a(a,m,u){const{parse:w,stringify:f}=r(a),{state:l,getState:d,setState:h}=o(a,(()=>s()?e(function(t,e){const n=Object.keys(t),o=Object.fromEntries(Object.entries(e||{}).filter((([t])=>n.includes(t))));return o}(a,u),a):w(c(a))));n((()=>{const t=()=>{const t=w(c(a));h(t)};return window.addEventListener(i,t),()=>{window.removeEventListener(i,t)}}),[h]);const p=t.useCallback(((t,e)=>{const n=`${window.location.pathname}${window.location.search}${window.location.hash}`,o="function"==typeof t,r=function(t){const e=Object.keys(t),n=window.location.search,o=new URLSearchParams(n),r=new URLSearchParams;return o.forEach(((t,n)=>!e.includes(n)&&r.set(n,t))),r}(a),s=o?t(d()):t?{...d(),...t}:d(),c=f(s,r);h(s);const i=`${window.location.pathname}${c.length?"?":""}${c}${window.location.hash}`;if(n!==i){const{replace:t,...n}=e||{};m[t?"replace":"push"](i,{...n})}}),[m,f,d]);return{updateState:h,updateUrl:p,state:l,getState:d}}function c(t){const e=new URLSearchParams(window.location.search),n=Object.keys(t),o=new URLSearchParams;return[...e.entries()].filter((([t])=>n.includes(t))).forEach((([t,e])=>o.set(t,e))),o.toString()}const i="popstate";export{a as useUrlStateBase};
+import t from"react";import{parseSsrQs as e}from"../next/parseSsrQs.mjs";import{useInsertionEffect as n}from"../useInsertionEffect.mjs";import{useSharedState as o}from"../useSharedState/useSharedState.mjs";import{useUrlEncode as r}from"../useUrlEncode/useUrlEncode.mjs";import{isSSR as s}from"../utils.mjs";function a(a,m,l){const{parse:u,stringify:w}=r(a),{state:f,getState:p,setState:d}=o(a,(()=>s()?e(function(t,e){const n=Object.keys(t),o=Object.fromEntries(Object.entries(e||{}).map((([t,e])=>[t.replaceAll("+"," "),e])).filter((([t])=>n.includes(t))));return o}(a,l),a):u(c(a))));n((()=>{const t=()=>{const t=u(c(a));d(t)};return window.addEventListener(i,t),()=>{window.removeEventListener(i,t)}}),[d]);const h=t.useCallback(((t,e)=>{const n=`${window.location.pathname}${window.location.search}${window.location.hash}`,o="function"==typeof t,r=function(t){const e=Object.keys(t),n=window.location.search,o=new URLSearchParams(n),r=new URLSearchParams;return o.forEach(((t,n)=>!e.includes(n)&&r.set(n,t))),r}(a),s=o?t(p()):t?{...p(),...t}:p(),c=w(s,r);d(s);const i=`${window.location.pathname}${c.length?"?":""}${c}${window.location.hash}`;if(n!==i){const{replace:t,...n}=e||{};m[t?"replace":"push"](i,{...n})}}),[m,w,p]);return{updateState:d,updateUrl:h,state:f,getState:p}}function c(t){const e=new URLSearchParams(window.location.search),n=Object.keys(t),o=new URLSearchParams;return[...e.entries()].filter((([t])=>n.includes(t))).forEach((([t,e])=>o.set(t,e))),o.toString()}const i="popstate";export{a as useUrlStateBase};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "state-in-url",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Library to store state in browser URL, includes hook for NextJS, hook for pure React, and low level helpers.",
   "homepage": "https://github.com/asmyshlyaev177/state-in-url#readme",
   "keywords": [