@multiplatform.one/router 5.0.26 → 6.0.0

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@multiplatform.one/router",
-  "version": "5.0.26",
+  "version": "6.0.0",
   "description": "multiplatform.one router with support for react-router-dom and react-navigation",
-  "sideEffects": false,
   "keywords": [
     "react",
     "react-native"
@@ -14,54 +13,65 @@
   },
   "license": "Apache-2.0",
   "author": "BitSpur <support@risserlabs.com> (https://risserlabs.com)",
-  "main": "dist/cjs",
-  "module": "dist/esm",
-  "module:jsx": "dist/jsx",
-  "source": "src/index.ts",
-  "types": "types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./types/index.d.ts",
-      "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js"
-    },
-    "./package.json": "./package.json"
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one"
   },
+  "source": "src/index.ts",
   "files": [
     "dist",
     "src",
     "types"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://gitlab.com/bitspur/multiplatform.one/multiplatform.one"
+  "sideEffects": false,
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "types/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "react-native": {
+        "import": "./dist/esm/index.native.js",
+        "require": "./dist/cjs/index.native.js"
+      },
+      "source": "./src/index.ts",
+      "types": "./types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/cjs/index.native.js"
+    }
   },
-  "engines": {
-    "node": ">=16.0.0"
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "multiplatform.one": "5.0.26"
+    "@multiplatform.one/platform": "6.0.0"
   },
   "devDependencies": {
-    "@react-navigation/native": "^7.0.14",
-    "@tamagui/build": "^1.122.6",
-    "@testing-library/react": "^14.1.2",
-    "@vitejs/plugin-react": "^4.2.1",
-    "jsdom": "^23.0.1",
-    "one": "^1.1.401",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "react-native": "0.74.5",
-    "react-router-dom": "^6.28.2",
-    "typescript": "~5.3.3",
-    "vite": "^6.0.3",
-    "vitest": "^1.4.0"
+    "@react-navigation/native": "^7.2.2",
+    "@tamagui/build": "2.0.0-rc.41",
+    "@testing-library/react": "^16.3.2",
+    "@vitejs/plugin-react": "^6.0.1",
+    "one": "^1.16.5",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "react-native": "0.83.2",
+    "react-router-dom": "^7.14.2",
+    "typescript": "~5.9.3",
+    "vite": "^8.0.10",
+    "vitest": "^4.1.5",
+    "@multiplatform.one/test-utils": "6.0.0",
+    "@multiplatform.one/config": "6.0.0"
   },
   "peerDependencies": {
-    "one": "^1.1.345",
-    "react": "~18.2.0",
-    "react-router-dom": "^6.28.0"
+    "one": "^1.4.10",
+    "react": "^19.1.0",
+    "react-router-dom": "^7.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
   },
+  "module:jsx": "dist/jsx",
   "scripts": {
     "build": "rm -rf dist types 2>/dev/null && tamagui-build --ts-project ./tsconfig.build.json",
     "test": "vitest run --coverage --coverage.provider=v8 --coverage.reporter=text --coverage.reporter=lcov --coverage.reporter=html",

package/src/hooks/README.md

@@ -0,0 +1,232 @@
+# URL State Management Hooks
+
+Cross-platform hooks for managing URL state in forms and other components. These hooks work seamlessly across web (React Router) and native (React Navigation) platforms.
+
+## Installation
+
+```bash
+npm install @multiplatform.one/router
+```
+
+## Hooks
+
+### `useSearchParams`
+
+Basic hook for reading and writing URL search parameters.
+
+```typescript
+import { useSearchParams } from "@multiplatform.one/router";
+
+function SearchForm() {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const handleSearch = (query: string) => {
+    setSearchParams({ q: query }, { debounceMs: 300 });
+  };
+
+  return (
+    <input
+      value={searchParams.q || ""}
+      onChange={(e) => handleSearch(e.target.value)}
+    />
+  );
+}
+```
+
+### `useUrlState`
+
+Advanced hook for syncing complex form state with URL parameters, with automatic serialization/deserialization.
+
+```typescript
+import { useUrlState } from "@multiplatform.one/router";
+
+interface FormState {
+  name: string;
+  age: number;
+  tags: string[];
+  settings: {
+    theme: "light" | "dark";
+    notifications: boolean;
+  };
+}
+
+function MyForm() {
+  const [formState, setFormState] = useUrlState<FormState>({
+    name: "",
+    age: 0,
+    tags: [],
+    settings: {
+      theme: "light",
+      notifications: true,
+    },
+  }, {
+    debounceMs: 500, // Debounce URL updates by 500ms
+  });
+
+  return (
+    <form>
+      <input
+        value={formState.name}
+        onChange={(e) => setFormState({ name: e.target.value })}
+      />
+      {/* Form fields... */}
+    </form>
+  );
+}
+```
+
+### `useTypedSearchParams`
+
+Type-safe parsing of URL parameters with schema validation.
+
+```typescript
+import { useTypedSearchParams } from "@multiplatform.one/router";
+
+function DataTable() {
+  const params = useTypedSearchParams({
+    page: {
+      default: 1,
+      parse: (value) => value ? parseInt(String(value), 10) : 1,
+    },
+    limit: {
+      default: 20,
+      parse: (value) => value ? parseInt(String(value), 10) : 20,
+    },
+    sortBy: {
+      default: "created",
+    },
+    sortOrder: {
+      default: "desc" as "asc" | "desc",
+      parse: (value) => value === "asc" ? "asc" : "desc",
+    },
+  });
+
+  // params is fully typed: { page: number; limit: number; sortBy: string; sortOrder: "asc" | "desc" }
+
+  return (
+    <div>
+      Page {params.page} of results
+    </div>
+  );
+}
+```
+
+### `useShareableUrl`
+
+Generate a shareable URL with current state.
+
+```typescript
+import { useShareableUrl } from "@multiplatform.one/router";
+
+function ShareButton() {
+  const shareableUrl = useShareableUrl();
+
+  const handleShare = () => {
+    navigator.clipboard.writeText(shareableUrl);
+  };
+
+  return (
+    <button onClick={handleShare}>
+      Copy Link: {shareableUrl}
+    </button>
+  );
+}
+```
+
+## Integration with TanStack Form
+
+Example of integrating URL state with TanStack Form:
+
+```typescript
+import { useForm } from "@tanstack/react-form";
+import { useUrlState } from "@multiplatform.one/router";
+
+function UrlSyncedForm() {
+  const [urlState, setUrlState] = useUrlState({
+    name: "",
+    email: "",
+    subscribe: false,
+  });
+
+  const form = useForm({
+    defaultValues: urlState,
+    onSubmit: async ({ value }) => {
+      // Submit logic
+      console.log("Submitting:", value);
+    },
+  });
+
+  // Sync form changes to URL
+  useEffect(() => {
+    const subscription = form.subscribe((state) => {
+      if (state.values) {
+        setUrlState(state.values);
+      }
+    });
+    return () => subscription.unsubscribe();
+  }, [form, setUrlState]);
+
+  return (
+    <form.Provider>
+      <form onSubmit={(e) => {
+        e.preventDefault();
+        form.handleSubmit();
+      }}>
+        <form.Field name="name">
+          {(field) => (
+            <input
+              value={field.state.value}
+              onChange={(e) => field.handleChange(e.target.value)}
+              onBlur={field.handleBlur}
+            />
+          )}
+        </form.Field>
+        {/* More fields... */}
+      </form>
+    </form.Provider>
+  );
+}
+```
+
+## Features
+
+- ✅ **Cross-platform**: Works on web, iOS, and Android
+- ✅ **Type-safe**: Full TypeScript support
+- ✅ **Debouncing**: Built-in debounce support for performance
+- ✅ **SSR-friendly**: Works with server-side rendering
+- ✅ **Flexible serialization**: Customize how state is stored in URLs
+- ✅ **Array & object support**: Handle complex data structures
+- ✅ **Default values**: Automatic fallback to defaults
+
+## Best Practices
+
+1. **Debounce text inputs** - Use 300-500ms debounce for text fields
+2. **Update on blur** - For better UX, consider updating URL on field blur
+3. **Keep URLs readable** - Use meaningful parameter names
+4. **Limit URL length** - Store only essential state in URLs
+5. **Handle hydration** - Use `defaultValue` for SSR compatibility
+
+## SSR Considerations
+
+These hooks are SSR-safe. During server-side rendering:
+
+- URL parameters are read from the request
+- Forms are pre-populated with URL values
+- Hydration preserves user input
+
+```typescript
+// SSR-safe form with URL state
+function SSRForm() {
+  const [state, setState] = useUrlState(
+    { search: "" },
+    { debounceMs: 500 }
+  );
+
+  return (
+    <input
+      defaultValue={state.search} // Use defaultValue for SSR
+      onChange={(e) => setState({ search: e.target.value })}
+    />
+  );
+}
+```

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export {
+  useSearchParams,
+  useUrlState,
+  useShareableUrl,
+  useTypedSearchParams,
+  type SearchParams,
+  type SetSearchParamsOptions,
+} from "./useUrlState";

package/src/hooks/useUrlState.spec.ts

@@ -0,0 +1,219 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as router from "../router";
+import { useSearchParams, useTypedSearchParams, useUrlState } from "./useUrlState";
+
+// Mock the router module
+vi.mock("../router", () => {
+  const mockSetParams = vi.fn();
+  return {
+    useParams: vi.fn(() => ({})),
+    useRouter: vi.fn(() => ({
+      setParams: mockSetParams,
+    })),
+  };
+});
+
+// Get the mocked functions
+const mockUseParams = router.useParams as ReturnType<typeof vi.fn>;
+const mockUseRouter = router.useRouter as ReturnType<typeof vi.fn>;
+
+describe("useUrlState", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("useSearchParams", () => {
+    it("should return current search params", () => {
+      mockUseParams.mockReturnValue({ foo: "bar", baz: "qux" });
+
+      const { result } = renderHook(() => useSearchParams());
+      const [params] = result.current;
+
+      expect(params).toEqual({ foo: "bar", baz: "qux" });
+    });
+
+    it("should update search params", () => {
+      const setParamsMock = vi.fn();
+      mockUseRouter.mockReturnValue({ setParams: setParamsMock });
+
+      const { result } = renderHook(() => useSearchParams());
+      const [, setParams] = result.current;
+
+      act(() => {
+        setParams({ foo: "bar" });
+      });
+
+      expect(setParamsMock).toHaveBeenCalledWith({ foo: "bar" });
+    });
+
+    it("should support function updates", () => {
+      const setParamsMock = vi.fn();
+      mockUseParams.mockReturnValue({ existing: "value" });
+      mockUseRouter.mockReturnValue({ setParams: setParamsMock });
+
+      const { result } = renderHook(() => useSearchParams());
+      const [, setParams] = result.current;
+
+      act(() => {
+        setParams((prev) => ({ ...prev, new: "param" }));
+      });
+
+      expect(setParamsMock).toHaveBeenCalledWith({
+        existing: "value",
+        new: "param",
+      });
+    });
+
+    it("should debounce updates when specified", async () => {
+      const setParamsMock = vi.fn();
+      mockUseRouter.mockReturnValue({ setParams: setParamsMock });
+
+      const { result } = renderHook(() => useSearchParams());
+      const [, setParams] = result.current;
+
+      act(() => {
+        setParams({ foo: "bar" }, { debounceMs: 100 });
+      });
+
+      expect(setParamsMock).not.toHaveBeenCalled();
+
+      await waitFor(
+        () => {
+          expect(setParamsMock).toHaveBeenCalledWith({ foo: "bar" });
+        },
+        { timeout: 200 },
+      );
+    });
+  });
+
+  describe("useUrlState", () => {
+    it("should initialize with default values", () => {
+      mockUseParams.mockReturnValue({});
+
+      const defaultValues = { name: "", age: 0, active: false };
+      const { result } = renderHook(() => useUrlState(defaultValues));
+      const [state] = result.current;
+
+      expect(state).toEqual(defaultValues);
+    });
+
+    it("should deserialize URL params", () => {
+      mockUseParams.mockReturnValue({
+        name: "John",
+        age: "25",
+        active: "true",
+      });
+
+      const defaultValues = { name: "", age: 0, active: false };
+      const { result } = renderHook(() => useUrlState(defaultValues));
+      const [state] = result.current;
+
+      expect(state).toEqual({
+        name: "John",
+        age: 25,
+        active: true,
+      });
+    });
+
+    it("should serialize state to URL params", () => {
+      const setParamsMock = vi.fn();
+      mockUseParams.mockReturnValue({});
+      mockUseRouter.mockReturnValue({ setParams: setParamsMock });
+
+      const defaultValues = { name: "", age: 0, active: false };
+      const { result } = renderHook(() => useUrlState(defaultValues, { debounceMs: 0 }));
+      const [, setState] = result.current;
+
+      act(() => {
+        setState({ name: "John", age: 25, active: true });
+      });
+
+      expect(setParamsMock).toHaveBeenCalledWith({
+        name: "John",
+        age: "25",
+        active: "true",
+      });
+    });
+
+    it("should handle arrays", () => {
+      mockUseParams.mockReturnValue({
+        tags: ["react", "typescript"],
+      });
+
+      const defaultValues = { tags: [] as string[] };
+      const { result } = renderHook(() => useUrlState(defaultValues));
+      const [state] = result.current;
+
+      expect(state).toEqual({
+        tags: ["react", "typescript"],
+      });
+    });
+
+    it("should handle objects with JSON serialization", () => {
+      mockUseParams.mockReturnValue({
+        config: '{"theme":"dark","lang":"en"}',
+      });
+
+      const defaultValues = { config: { theme: "light", lang: "en" } };
+      const { result } = renderHook(() => useUrlState(defaultValues));
+      const [state] = result.current;
+
+      expect(state).toEqual({
+        config: { theme: "dark", lang: "en" },
+      });
+    });
+  });
+
+  describe("useTypedSearchParams", () => {
+    it("should parse params with schema", () => {
+      mockUseParams.mockReturnValue({
+        page: "2",
+        limit: "50",
+        search: "test",
+      });
+
+      const schema = {
+        page: {
+          default: 1,
+          parse: (value: string | string[] | undefined) =>
+            value ? Number.parseInt(String(value), 10) : 1,
+        },
+        limit: {
+          default: 20,
+          parse: (value: string | string[] | undefined) =>
+            value ? Number.parseInt(String(value), 10) : 20,
+        },
+        search: {
+          default: "",
+        },
+      };
+
+      const { result } = renderHook(() => useTypedSearchParams(schema));
+
+      expect(result.current).toEqual({
+        page: 2,
+        limit: 50,
+        search: "test",
+      });
+    });
+
+    it("should use defaults for missing params", () => {
+      mockUseParams.mockReturnValue({});
+
+      const schema = {
+        page: { default: 1 },
+        limit: { default: 20 },
+        search: { default: "" },
+      };
+
+      const { result } = renderHook(() => useTypedSearchParams(schema));
+
+      expect(result.current).toEqual({
+        page: 1,
+        limit: 20,
+        search: "",
+      });
+    });
+  });
+});