@koine/browser 2.0.0-beta.131 → 2.0.0-beta.133

package/createStorage.d.ts

@@ -1,12 +1,59 @@
+/**
+ * @category storage
+ */
 export type CreateStorageConfig = Record<string, any>;
+/**
+ * Utility to create a storage instance to interact with `localStorage` using
+ * encrypted (encoded) key/values.
+ *
+ * @category storage
+ */
 export declare let createStorage: <T extends CreateStorageConfig>(config: Partial<T>, useSessionStorage?: boolean) => {
+    /**
+     * Get all storage value (it uses `localStorage.get()`).
+     *
+     * Unparseable values with `JSON.parse()` return their value as it is.
+     * On ssr or if the given `key` argument is not found `defaultValue` is
+     * returned, otherwise `null`.
+     */
     get<TKey extends Extract<keyof T, string>>(key: TKey, defaultValue?: null | T[TKey]): T[TKey] | null;
+    /**
+     * Get all storage values (it uses `localStorage.get()`).
+     *
+     * `undefined` and `null` values are not returned.
+     */
     getAll(defaultValues?: Partial<T>): T;
+    /**
+     * Set a storage value (it uses `localStorage.set()`).
+     *
+     * Non-string values are stringified with `JSON.stringify()`
+     */
     set<TKey extends Extract<keyof T, string>>(key: TKey, value?: T[TKey]): void;
+    /**
+     * Set all given storage values (it uses `localStorage.set()`).
+     *
+     * Non-string values are stringified with `JSON.stringify()`, `undefined`
+     * and `null` values are removed from the storage
+     */
     setMany(newValues: Partial<T>): void;
+    /**
+     * Check if a storage value is _truthy_ (it uses `localStorage.get()`).
+     */
     has<TKey extends Extract<keyof T, string>>(key: TKey): any;
+    /**
+     * Remove a storage value (it uses `localStorage.remove()`).
+     */
     remove<TKey extends Extract<keyof T, string>>(key: TKey): void;
+    /**
+     * Clear all storage values (it uses `localStorage.remove()`).
+     */
     clear(): void;
+    /**
+     * Watch a storage value changes, this needs to be executed only in browser
+     * context (it uses `window.addEventListener("storage")`).
+     *
+     * Inspiration from [Multi Tab Logout in React — Redux](https://medium.com/front-end-weekly/multi-tab-logout-in-react-redux-4715f071c7fa)
+     */
     watch: <TKey extends keyof T>(keyToWatch: TKey, onRemoved?: () => void, onAdded?: () => void) => () => void | undefined;
 };
 export default createStorage;

package/getZonedDate.d.ts

@@ -1,2 +1,16 @@
+/**
+ * It returns a `Date` object from a date `string` adjusted on the user timeZone,
+ * if a timeZone is not provided we try getting it from the `Intl` browwser native
+ * API. It gracefully falls back returning a _non-timezone-based_ `Date`.
+ *
+ * @category date
+ *
+ * @resources
+ * - to get the timeZone client side see [this article](https://attacomsian.com/blog/javascript-current-timezone)
+ * - for converting the date based on the time zone [date-fns docs](https://date-fns.org/v2.27.0/docs/Time-Zones) and [date-fns-tz docs](https://github.com/marnusw/date-fns-tz)
+ *
+ * @param dateString A parseable date as string, `Z` is automatically suffixed if not present to correctly get time zone based time from a UTC date.
+ * @param timeZone Optionally pass a timeZone (e.g. from user preference or from the server), it falls back trying to read it from the `Intl` browwser native API.
+ */
 export declare let getZonedDate: (dateString?: string, timeZone?: string) => Date;
 export default getZonedDate;

package/gtag.d.ts

@@ -1,2 +1,13 @@
+/**
+ * @category analytics-google
+ *
+ * If you like you could add to your globals `.d.ts` types:
+ *
+ * ```ts
+ * declare interface Window {
+ *   gtag: <T extends unknown[]>(...args: T) => void;
+ * }
+ * ```
+ */
 export declare let gtag: <T extends unknown[]>(...args: T) => void;
 export default gtag;

package/gtagPageview.d.ts

@@ -3,5 +3,8 @@ export type GtmPageviewArgs = [
     page_title?: string,
     page_location?: string
 ];
+/**
+ * @category analytics-google
+ */
 export declare let gtagPageview: (page_path?: string | undefined, page_title?: string | undefined, page_location?: string | undefined) => void;
 export default gtagPageview;

package/isIE.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @category detect
+ * @category is
+ * @see https://stackoverflow.com/a/21712356/12285349
+ */
 export declare let isIE: (ssrValue?: boolean) => boolean;
 export default isIE;

package/isMobile.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @category detect
+ * @category is
+ * @see https://stackoverflow.com/a/3540295
+ */
 export declare let isMobile: (ssrValue?: boolean) => boolean;
 export default isMobile;

package/listenUrlSearch.d.ts

@@ -1,3 +1,20 @@
+/**
+ * @param prevLocationSearch The previous URL search query e.g. `?myparam=mvalue`
+ * @param newLocationSearch The previous URL search query e.g. `?myparam=mvalue`
+ */
 type Handler = (prevLocationSearch: string, newLocationSearch: string) => void;
+/**
+ * Here we extend and mutate the native `window.history` object so that multiple
+ * scripts can add url change handlers without interfering each other and using
+ * the same single listener.
+ *
+ * @borrows [SO answer](https://stackoverflow.com/a/42727249/1938970)
+ *
+ * @category location
+ * @category navigation
+ * @category events
+ *
+ * @returns A de-register function to remove the handler
+ */
 export declare let listenUrlSearch: (handler: Handler) => () => void;
 export default listenUrlSearch;

package/listenUrlSearchParams.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @category events
+ * @category navigation
+ * @category events
+ */
 export declare let listenUrlSearchParams: (paramName: string, handler: (paramNewValue: string | null) => void) => () => void;
 export default listenUrlSearchParams;

package/navigateToHash.d.ts

@@ -1,2 +1,8 @@
+/**
+ * It updates the browser's location hash by replacing the history state.
+ * The non-silent standard way would simply be `location.hash = "#new-hash"`
+ *
+ * @category location
+ */
 export declare let navigateToHash: (hash?: string) => void;
 export default navigateToHash;

package/navigateToHashParams.d.ts

@@ -1,3 +1,9 @@
 import { type AnyQueryParams } from "@koine/utils";
+/**
+ * It updates the `location.hash` with the given query params, it uses `location.hash`
+ * if a second argument `hash` is not provded
+ *
+ * @category location
+ */
 export declare let navigateToHashParams: (params?: string | AnyQueryParams, hash?: string) => string;
 export default navigateToHashParams;

package/navigateToMergedHashParams.d.ts

@@ -1,3 +1,8 @@
 import { type AnyQueryParams } from "@koine/utils";
+/**
+ * It updates the "query params" within the `location.hash`, it uses `location`
+ *
+ * @category location
+ */
 export declare let navigateToMergedHashParams: (params?: NonNullable<AnyQueryParams>, hash?: string) => string;
 export default navigateToMergedHashParams;

package/navigateToMergedParams.d.ts

@@ -1,3 +1,9 @@
 import { type AnyQueryParams } from "@koine/utils";
+/**
+ * Merge current URL query parameters with the given ones, it uses `history`.
+ *
+ * @category location
+ * @param replace Replace URL instead of pushing it in the history stack. By default it pushes it.
+ */
 export declare let navigateToMergedParams: (params?: NonNullable<AnyQueryParams>, replace?: boolean) => string;
 export default navigateToMergedParams;

package/navigateToParams.d.ts

@@ -1,3 +1,10 @@
 import { type AnyQueryParams } from "@koine/utils";
+/**
+ * Change current URL query parameters, it uses `history`.
+ *
+ * @category location
+ * @param replace Replace URL instead of pushing it in the history stack. By default it pushes it.
+ * @returns The query string with initial `?`
+ */
 export declare let navigateToParams: (params?: string | AnyQueryParams, replace?: boolean) => string;
 export default navigateToParams;

package/navigateToUrl.d.ts

@@ -1,2 +1,7 @@
+/**
+ * It updates the browser's location URL with global `history` object
+ *
+ * @category location
+ */
 export declare let navigateToUrl: (url?: string, replace?: boolean) => void;
 export default navigateToUrl;

package/navigateWithoutUrlParam.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Remove URL query parameter, it uses `history`
+ *
+ * @category location
+ * @param replace Replace URL instead of pushing it in the history stack. By default it pushes it.
+ */
 export declare let navigateWithoutUrlParam: (paramName?: string, replace?: boolean) => string;
 export default navigateWithoutUrlParam;

package/package.json

@@ -2,8 +2,8 @@
   "name": "@koine/browser",
   "sideEffects": false,
   "dependencies": {
-    "@koine/dom": "2.0.0-beta.131",
-    "@koine/utils": "2.0.0-beta.131"
+    "@koine/dom": "2.0.0-beta.133",
+    "@koine/utils": "2.0.0-beta.133"
   },
   "peerDependenciesMeta": {
     "date-fns-tz": {
@@ -130,5 +130,5 @@
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
   "types": "./index.esm.d.ts",
-  "version": "2.0.0-beta.131"
+  "version": "2.0.0-beta.133"
 }

package/redirectTo.d.ts

@@ -1,3 +1,9 @@
 import { type AnyQueryParams } from "@koine/utils";
+/**
+ * Redirect to url with params {optionally}, removes eventual trailing question
+ * marks from the given URL, it uses `location`
+ *
+ * @category location
+ */
 export declare let redirectTo: (url: string, params?: AnyQueryParams) => void;
 export default redirectTo;

package/storage.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Storage, for `localStorage` and `sessionStorage`
+ *
+ * @category storage
+ */
 export declare let storage: {
     l: {
         get: <TKey extends string, TValue = any>(key: TKey, transform?: ((value: string) => TValue) | undefined, defaultValue?: TValue | null | undefined) => NonNullable<TValue> | null;

package/storageClient.d.ts

@@ -1,4 +1,12 @@
+/**
+ * @category storage
+ */
 export type StorageClientConfig = Record<string, any>;
+/**
+ * Super minifiable `local/session Storage` client creator with SSR safety
+ *
+ * @category storage
+ */
 export declare let storageClient: <TConfig extends StorageClientConfig = StorageClientConfig>(useSessionStorage?: boolean) => {
     get: <TKey extends Extract<keyof TConfig, string>, TValue = TConfig[TKey]>(key: TKey, transform?: (value: string) => TValue, defaultValue?: null | TValue) => NonNullable<TValue> | null;
     set: <TKey extends Extract<keyof TConfig, string>, TValue_1 = TConfig[TKey]>(key: TKey, value?: TValue_1, transform?: (value: any) => string) => void;