@multiplatform.one/router 5.0.27 → 6.0.1

package/src/hooks/useUrlState.ts

@@ -0,0 +1,231 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { isWeb } from "@multiplatform.one/platform";
+import { useParams, useRouter } from "../router";
+
+export type SearchParams = Record<string, string | string[] | undefined>;
+
+export interface SetSearchParamsOptions {
+  replace?: boolean;
+  debounceMs?: number;
+}
+
+/**
+ * Cross-platform hook for managing URL search parameters
+ * Works with both React Router (web) and React Navigation (native)
+ */
+export function useSearchParams(): [
+  SearchParams,
+  (
+    params: SearchParams | ((prev: SearchParams) => SearchParams),
+    options?: SetSearchParamsOptions,
+  ) => void,
+] {
+  const router = useRouter();
+  const currentParams = useParams();
+  const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  // Parse current params into a more usable format
+  const searchParams = useMemo<SearchParams>(() => {
+    const params: SearchParams = {};
+    Object.entries(currentParams).forEach(([key, value]) => {
+      if (value !== undefined && value !== null) {
+        params[key] = value as string | string[];
+      }
+    });
+    return params;
+  }, [currentParams]);
+
+  const setSearchParams = useCallback(
+    (
+      newParams: SearchParams | ((prev: SearchParams) => SearchParams),
+      options: SetSearchParamsOptions = {},
+    ) => {
+      const { replace: _replace = true, debounceMs = 0 } = options;
+
+      const updateParams = () => {
+        const updatedParams = typeof newParams === "function" ? newParams(searchParams) : newParams;
+
+        // Filter out undefined values
+        const cleanParams: Record<string, string | string[]> = {};
+        Object.entries(updatedParams).forEach(([key, value]) => {
+          if (value !== undefined && value !== null && value !== "") {
+            cleanParams[key] = value;
+          }
+        });
+
+        // Use router.setParams to update the URL
+        router.setParams(cleanParams as any);
+      };
+
+      if (debounceMs > 0) {
+        if (debounceTimerRef.current) {
+          clearTimeout(debounceTimerRef.current);
+        }
+        debounceTimerRef.current = setTimeout(updateParams, debounceMs);
+      } else {
+        updateParams();
+      }
+    },
+    [router, searchParams],
+  );
+
+  // Cleanup debounce timer on unmount
+  useEffect(() => {
+    return () => {
+      if (debounceTimerRef.current) {
+        clearTimeout(debounceTimerRef.current);
+      }
+    };
+  }, []);
+
+  return [searchParams, setSearchParams];
+}
+
+/**
+ * Hook for syncing form state with URL parameters
+ * Provides automatic serialization/deserialization and debouncing
+ */
+export function useUrlState<T extends Record<string, any>>(
+  defaultValues: T,
+  options: {
+    debounceMs?: number;
+    serialize?: (value: T) => SearchParams;
+    deserialize?: (params: SearchParams) => T;
+  } = {},
+): [T, (newState: Partial<T> | ((prev: T) => Partial<T>)) => void] {
+  const {
+    debounceMs = 500,
+    serialize = (value) => {
+      // Default serialization: convert to string
+      const params: SearchParams = {};
+      Object.entries(value).forEach(([key, val]) => {
+        if (val !== undefined && val !== null && val !== "") {
+          if (Array.isArray(val)) {
+            params[key] = val.map(String);
+          } else if (typeof val === "object") {
+            params[key] = JSON.stringify(val);
+          } else {
+            params[key] = String(val);
+          }
+        }
+      });
+      return params;
+    },
+    deserialize = (params) => {
+      // Default deserialization: parse JSON for objects
+      const result: any = {};
+      Object.entries(params).forEach(([key, value]) => {
+        if (key in defaultValues) {
+          const defaultValue = defaultValues[key];
+          if (value === undefined) {
+            result[key] = defaultValue;
+          } else if (Array.isArray(defaultValue)) {
+            result[key] = Array.isArray(value) ? value : [value];
+          } else if (typeof defaultValue === "boolean") {
+            result[key] = value === "true";
+          } else if (typeof defaultValue === "number") {
+            result[key] = Number(value);
+          } else if (typeof defaultValue === "object" && defaultValue !== null) {
+            try {
+              result[key] = JSON.parse(String(value));
+            } catch {
+              result[key] = defaultValue;
+            }
+          } else {
+            result[key] = value;
+          }
+        }
+      });
+      // Fill in missing keys with defaults
+      Object.keys(defaultValues).forEach((key) => {
+        if (!(key in result)) {
+          result[key] = defaultValues[key];
+        }
+      });
+      return result as T;
+    },
+  } = options;
+
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  // Initialize state from URL or defaults
+  const currentState = useMemo(() => {
+    return deserialize(searchParams);
+  }, [searchParams, deserialize]);
+
+  const setState = useCallback(
+    (newState: Partial<T> | ((prev: T) => Partial<T>)) => {
+      const updatedState = typeof newState === "function" ? newState(currentState) : newState;
+
+      const mergedState = { ...currentState, ...updatedState };
+      const serialized = serialize(mergedState);
+
+      setSearchParams(serialized, { debounceMs });
+    },
+    [currentState, serialize, setSearchParams, debounceMs],
+  );
+
+  return [currentState, setState];
+}
+
+/**
+ * Hook for creating shareable URLs with current state
+ */
+export function useShareableUrl(): string {
+  const params = useParams();
+
+  const shareableUrl = useMemo(() => {
+    if (!isWeb || typeof window === "undefined") {
+      return "";
+    }
+
+    const url = new URL(window.location.href);
+    url.search = "";
+
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined && value !== null && value !== "") {
+        if (Array.isArray(value)) {
+          value.forEach((v) => url.searchParams.append(key, String(v)));
+        } else {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    });
+
+    return url.toString();
+  }, [params]);
+
+  return shareableUrl;
+}
+
+/**
+ * Hook for parsing URL parameters with type safety
+ */
+export function useTypedSearchParams<T extends Record<string, any>>(schema: {
+  [K in keyof T]: {
+    default: T[K];
+    parse?: (value: string | string[] | undefined) => T[K];
+  };
+}): T {
+  const params = useParams();
+
+  const typedParams = useMemo(() => {
+    const result: any = {};
+
+    Object.entries(schema).forEach(([key, config]) => {
+      const rawValue = params[key];
+
+      if (config.parse) {
+        result[key] = config.parse(rawValue);
+      } else if (rawValue === undefined) {
+        result[key] = config.default;
+      } else {
+        result[key] = rawValue;
+      }
+    });
+
+    return result as T;
+  }, [params, schema]);
+
+  return typedParams;
+}

package/src/index.storybook.ts

@@ -0,0 +1,3 @@
+export { useRouter, usePathname, useParams, Link } from "./router/EmptyRouter";
+export * from "./types";
+export * from "./hooks";

package/src/index.ts

@@ -1,23 +1,3 @@
-/*
- * File: /src/index.ts
- * Project: @multiplatform.one/router
- * File Created: 10-01-2025 15:02:36
- * Author: Clay Risser
- * -----
- * BitSpur (c) Copyright 2021 - 2025
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 export * from "./router/index";
 export * from "./types";
+export * from "./hooks";

package/src/router/EmptyRouter.tsx

@@ -0,0 +1,50 @@
+import type { Href, LinkComponent, Router } from "../types";
+
+const prefix = "[router]";
+
+export const useRouter = (): Router => {
+  return {
+    back: () => console.log(prefix, "back()"),
+    canGoBack: () => false,
+    push: (href: Href) => console.log(prefix, "push", String(href)),
+    navigate: (href: Href) => console.log(prefix, "navigate", String(href)),
+    replace: (href: Href) => console.log(prefix, "replace", String(href)),
+    dismiss: (count?: number) => console.log(prefix, "dismiss", count ?? 1),
+    dismissAll: () => console.log(prefix, "dismissAll()"),
+    canDismiss: () => false,
+    setParams: (params) => console.log(prefix, "setParams", params),
+    subscribe: (listener) => {
+      listener("success");
+      return () => {};
+    },
+    onLoadState: (listener) => {
+      listener("loaded");
+      return () => {};
+    },
+  };
+};
+
+export const usePathname = (): string => "/";
+
+export const useParams = () => ({});
+
+export const Link: LinkComponent = ({ href, replace, children, ...props }) => {
+  const handleClick = (e: React.MouseEvent) => {
+    e.preventDefault();
+    console.log(prefix, replace ? "replace" : "push", String(href));
+  };
+  return (
+    <a href={href as string} onClick={handleClick} {...props}>
+      {children}
+    </a>
+  );
+};
+
+Link.resolveHref = (href: Href) => href.toString();
+
+export function useUrlState<T extends Record<string, any>>(
+  defaultValues: T,
+): [T, (newState: Partial<T> | ((prev: T) => Partial<T>)) => void] {
+  const setState = () => {};
+  return [defaultValues, setState];
+}

package/src/router/{reactRouter.tsx → ReactRouter.tsx}

@@ -1,29 +1,9 @@
-/**
- * File: /src/router/reactRouter.tsx
- * Project: @multiplatform.one/router
- * File Created: 24-01-2025 16:56:40
- * Author: Clay Risser
- * -----
- * BitSpur (c) Copyright 2021 - 2025
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 import {
   Link as ReactRouterLink,
   useLocation,
   useNavigate,
   useParams as useReactParams,
+  useSearchParams as useReactSearchParams,
 } from "react-router-dom";
 import type {
   Href,
@@ -73,7 +53,32 @@ export const useRouter = (): Router => {
 
 export const usePathname = (): string => useLocation().pathname;
 
-export const useParams = useReactParams;
+// Combine route params and search params for React Router
+export const useParams = () => {
+  const routeParams = useReactParams();
+  const [searchParams] = useReactSearchParams();
+  const params: Record<string, string | string[] | undefined> = {};
+
+  // Add route params
+  Object.entries(routeParams).forEach(([key, value]) => {
+    if (value !== undefined) {
+      params[key] = value;
+    }
+  });
+
+  // Add search params
+  searchParams.forEach((value, key) => {
+    if (params[key]) {
+      // If key already exists from route params, make it an array
+      const existing = params[key];
+      params[key] = Array.isArray(existing) ? [...existing, value] : [existing as string, value];
+    } else {
+      params[key] = value;
+    }
+  });
+
+  return params;
+};
 
 export const Link: LinkComponent = ({ href, replace, children, ...props }) => (
   <ReactRouterLink to={href as string} replace={replace} {...props}>

package/src/router/index.storybook-expo.tsx

@@ -1,22 +1 @@
-/**
- * File: /src/router/index.storybook-expo.tsx
- * Project: @multiplatform.one/router
- * File Created: 23-01-2025 15:12:32
- * Author: Clay Risser
- * -----
- * BitSpur (c) Copyright 2021 - 2025
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-export * from "./emptyRouter";
+export * from "./EmptyRouter";

package/src/router/index.storybook.tsx

@@ -1,22 +1 @@
-/**
- * File: /src/router/index.storybook.tsx
- * Project: @multiplatform.one/router
- * File Created: 23-01-2025 15:12:32
- * Author: Clay Risser
- * -----
- * BitSpur (c) Copyright 2021 - 2025
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-export * from "./emptyRouter";
+export * from "./EmptyRouter";

package/src/router/index.tsx

@@ -1,97 +1 @@
-/**
- * File: /src/router/index.tsx
- * Project: @multiplatform.one/router
- * File Created: 23-01-2025 15:17:57
- * Author: Clay Risser
- * -----
- * BitSpur (c) Copyright 2021 - 2025
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import {
-  Link as OneLink,
-  usePathname as useOnePathname,
-  useRouter as useOneRouter,
-} from "one";
-import type {
-  Href,
-  LinkComponent,
-  LoadingState,
-  ResultState,
-  Router,
-} from "../types";
-
-const mapResultState = (state: unknown): ResultState => {
-  return state === "success" ? "success" : "error";
-};
-
-const mapLoadingState = (state: unknown): LoadingState => {
-  if (state === "loaded") return "loaded";
-  if (state === "loading") return "loading";
-  return "error";
-};
-
-export const useRouter = (): Router => {
-  const router = useOneRouter();
-  return {
-    back: () => router.back(),
-    canGoBack: () => router.canGoBack(),
-    push: (href: Href) => router.push(href),
-    navigate: (href: Href) => router.navigate(href),
-    replace: (href: Href) => router.replace(href),
-    dismiss: (count?: number) => router.dismiss(count),
-    dismissAll: () => router.dismissAll(),
-    canDismiss: () => router.canDismiss(),
-    setParams: router.setParams,
-    subscribe: (listener) => {
-      const oneListener = (state: unknown) => {
-        listener(mapResultState(state));
-      };
-      return router.subscribe(oneListener);
-    },
-    onLoadState: (listener) => {
-      const oneListener = (state: unknown) => {
-        listener(mapLoadingState(state));
-      };
-      return router.onLoadState(oneListener);
-    },
-  };
-};
-
-export const usePathname = useOnePathname;
-
-export const useParams = () => {
-  const pathname = useOnePathname();
-  const searchParams = new URLSearchParams(pathname);
-  const params: Record<string, string> = {};
-  searchParams.forEach((value, key) => {
-    params[key] = value;
-  });
-  return params;
-};
-
-export const Link: LinkComponent = ({
-  href,
-  replace,
-  children,
-  style,
-  className,
-  ...props
-}) => (
-  <OneLink href={href} replace={replace} {...props}>
-    {children}
-  </OneLink>
-);
-
-Link.resolveHref = (href: Href) => href.toString();
+export { Link, useParams, usePathname, useRouter } from "one";

package/src/router/index.webext.tsx

@@ -1,22 +1 @@
-/**
- * File: /src/router/index.webext.tsx
- * Project: @multiplatform.one/router
- * File Created: 10-01-2025 15:02:36
- * Author: Clay Risser
- * -----
- * BitSpur (c) Copyright 2021 - 2025
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-export * from "./reactRouter";
+export * from "./ReactRouter";

package/src/types.tsx

@@ -1,26 +1,5 @@
-/**
- * File: /src/types.tsx
- * Project: @multiplatform.one/router
- * File Created: 23-01-2025 15:28:42
- * Author: Clay Risser
- * -----
- * BitSpur (c) Copyright 2021 - 2025
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 import type { OneRouter } from "one";
-import type { CSSProperties, ReactNode } from "react";
+import type { CSSProperties, ReactElement, ReactNode } from "react";
 
 export type Href = OneRouter.Href<{ __branded__: any }>;
 export type LoadingState = "loading" | "loaded" | "error";
@@ -49,7 +28,7 @@ export interface Router {
 
 export type UseRouter = () => Router;
 export type UsePathname = () => string;
-export type UseParams = () => Record<string, string>;
+export type UseParams = () => Record<string, string | string[] | undefined>;
 
 export interface LinkProps {
   href: Href;
@@ -61,6 +40,6 @@ export interface LinkProps {
 }
 
 export interface LinkComponent {
-  (props: LinkProps): JSX.Element;
+  (props: LinkProps): ReactElement;
   resolveHref: (href: Href) => string;
 }

package/dist/cjs/index.js

@@ -1,16 +0,0 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from == "object" || typeof from == "function")
-    for (let key of __getOwnPropNames(from))
-      !__hasOwnProp.call(to, key) && key !== except && __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  return to;
-}, __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: !0 }), mod);
-var index_exports = {};
-module.exports = __toCommonJS(index_exports);
-__reExport(index_exports, require("./router/index"), module.exports);
-__reExport(index_exports, require("./types"), module.exports);
-//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1,6 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/index.ts"],
-  "mappings": ";;;;;;;;;;;AAAA;AAAA;AAqBA,0BAAc,2BArBd;AAsBA,0BAAc,oBAtBd;",
-  "names": []
-}

package/dist/cjs/router/emptyRouter.cjs

@@ -1,55 +0,0 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-    for (var name in all) __defProp(target, name, {
-      get: all[name],
-      enumerable: !0
-    });
-  },
-  __copyProps = (to, from, except, desc) => {
-    if (from && typeof from == "object" || typeof from == "function") for (let key of __getOwnPropNames(from)) !__hasOwnProp.call(to, key) && key !== except && __defProp(to, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    });
-    return to;
-  };
-var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
-  value: !0
-}), mod);
-var emptyRouter_exports = {};
-__export(emptyRouter_exports, {
-  Link: () => Link,
-  useParams: () => useParams,
-  usePathname: () => usePathname,
-  useRouter: () => useRouter
-});
-module.exports = __toCommonJS(emptyRouter_exports);
-var import_jsx_runtime = require("react/jsx-runtime");
-const useRouter = () => ({
-    back: () => {},
-    canGoBack: () => !1,
-    push: () => {},
-    navigate: () => {},
-    replace: () => {},
-    dismiss: () => {},
-    dismissAll: () => {},
-    canDismiss: () => !1,
-    setParams: () => {},
-    subscribe: listener => (listener("success"), () => {}),
-    onLoadState: listener => (listener("loaded"), () => {})
-  }),
-  usePathname = () => "/",
-  useParams = () => ({}),
-  Link = ({
-    href,
-    replace,
-    children,
-    ...props
-  }) => /* @__PURE__ */(0, import_jsx_runtime.jsx)("a", {
-    href,
-    ...props,
-    children
-  });
-Link.resolveHref = href => href.toString();