@react-md/core 1.0.0-next.19 → 1.0.0-next.20

package/dist/storage/internalUtils.js

@@ -0,0 +1,22 @@
+import { identity } from "../utils/identity.js";
+/**
+ * @since 6.0.0
+ * @internal
+ */ export const defaultLocalStorageSerializer = (value)=>typeof value === "string" ? value : `${value}`;
+/**
+ * @since 6.0.0
+ * @internal
+ */ export function getStorageSerializers(options) {
+    const { initialValue } = options;
+    // this allows for strings to automatically be stored as-is instead of adding
+    // additional quotes around then with JSON.stringify
+    const raw = options.raw ?? typeof initialValue === "string";
+    const serializer = options.serializer ?? (raw ? defaultLocalStorageSerializer : JSON.stringify);
+    const deserializer = options.deserializer ?? (raw && typeof initialValue === "string" ? identity : JSON.parse);
+    return {
+        serializer,
+        deserializer
+    };
+}
+
+//# sourceMappingURL=internalUtils.js.map

package/dist/storage/internalUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/internalUtils.ts"],"sourcesContent":["import { identity } from \"../utils/identity.js\";\nimport { type StorageDeserializer, type StorageSerializers } from \"./types.js\";\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport const defaultLocalStorageSerializer = (value: unknown): string =>\n  typeof value === \"string\" ? value : `${value}`;\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface GetStorageSerializers<T> extends StorageSerializers<T> {\n  raw?: boolean;\n  initialValue: T;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport function getStorageSerializers<T>(\n  options: GetStorageSerializers<T>\n): Required<StorageSerializers<T>> {\n  const { initialValue } = options;\n\n  // this allows for strings to automatically be stored as-is instead of adding\n  // additional quotes around then with JSON.stringify\n  const raw = options.raw ?? typeof initialValue === \"string\";\n  const serializer =\n    options.serializer ??\n    (raw ? defaultLocalStorageSerializer : JSON.stringify);\n  const deserializer: StorageDeserializer<T> =\n    options.deserializer ??\n    (raw && typeof initialValue === \"string\" ? identity : JSON.parse);\n\n  return {\n    serializer,\n    deserializer,\n  };\n}\n"],"names":["identity","defaultLocalStorageSerializer","value","getStorageSerializers","options","initialValue","raw","serializer","JSON","stringify","deserializer","parse"],"mappings":"AAAA,SAASA,QAAQ,QAAQ,uBAAuB;AAGhD;;;CAGC,GACD,OAAO,MAAMC,gCAAgC,CAACC,QAC5C,OAAOA,UAAU,WAAWA,QAAQ,GAAGA,OAAO,CAAC;AAWjD;;;CAGC,GACD,OAAO,SAASC,sBACdC,OAAiC;IAEjC,MAAM,EAAEC,YAAY,EAAE,GAAGD;IAEzB,6EAA6E;IAC7E,oDAAoD;IACpD,MAAME,MAAMF,QAAQE,GAAG,IAAI,OAAOD,iBAAiB;IACnD,MAAME,aACJH,QAAQG,UAAU,IACjBD,CAAAA,MAAML,gCAAgCO,KAAKC,SAAS,AAAD;IACtD,MAAMC,eACJN,QAAQM,YAAY,IACnBJ,CAAAA,OAAO,OAAOD,iBAAiB,WAAWL,WAAWQ,KAAKG,KAAK,AAAD;IAEjE,OAAO;QACLJ;QACAG;IACF;AACF"}

package/dist/storage/types.d.ts

@@ -0,0 +1,75 @@
+import { type UseStateInitializer, type UseStateSetter } from "../types.js";
+/** @since 6.0.0 */
+export type StorageSerializer<T> = (value: T) => string;
+/** @since 6.0.0 */
+export type StorageDeserializer<T> = (item: string) => T;
+/** @since 6.0.0 */
+export interface StorageSerializers<T> {
+    /**
+     * An optional function to serialize the `value` before storing it in local
+     * storage.
+     *
+     * @defaultValue `JSON.stringify`
+     */
+    serializer?: StorageSerializer<T>;
+    /**
+     * An optional function to deserialize the `value` if the item existed in
+     * local storage.
+     *
+     * @defaultValue `JSON.parse`
+     */
+    deserializer?: StorageDeserializer<T>;
+}
+/** @since 6.0.0 */
+export interface StorageOptions<T> extends StorageSerializers<T> {
+    /**
+     * The storage key name to use. This can be set to an empty string for
+     * internal usage of conditionally saving items to storage.
+     */
+    key: string;
+    /**
+     * The default value to use if an item does not exist in storage.
+     */
+    defaultValue: UseStateInitializer<T>;
+    /**
+     * Set this to `true` to update:
+     *
+     * - the default {@link serializer} to be:
+     * ```
+     * typeof value === "string" ? value : `${value}`
+     * ```
+     * - the default {@link deserializer} to not call `JSON.parse` if the
+     *   {@link defaultValue} is a string.
+     *
+     * @defaultValue `typeof defaultValue === 'string'`
+     */
+    raw?: boolean;
+    /**
+     * Set this to `true` to require a manual `persist()` or `remove()` call
+     * to update the storage value.
+     *
+     * @defaultValue `false`
+     */
+    manual?: boolean;
+    /** @defaultValue `globalThis.localStorage` */
+    storage?: Storage;
+}
+/** @since 6.0.0 */
+export interface StorageImplementation<T> {
+    value: T;
+    /**
+     * Updates the {@link value} in state. When the
+     * {@link StorageOptions.manual} option is `false`, the value will
+     * also be updated in local storage immediately.
+     */
+    setValue: UseStateSetter<T>;
+    /**
+     * Remove the item from local storage.
+     */
+    remove: () => void;
+    /**
+     * Manually persist the current {@link value} into local storage. This is only
+     * useful if the {@link StorageOptions.manual} option is `true`.
+     */
+    persist: () => void;
+}

package/dist/storage/types.js

@@ -0,0 +1,3 @@
+/** @since 6.0.0 */ export { };
+
+//# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/types.ts"],"sourcesContent":["import { type UseStateInitializer, type UseStateSetter } from \"../types.js\";\n\n/** @since 6.0.0 */\nexport type StorageSerializer<T> = (value: T) => string;\n\n/** @since 6.0.0 */\nexport type StorageDeserializer<T> = (item: string) => T;\n\n/** @since 6.0.0 */\nexport interface StorageSerializers<T> {\n  /**\n   * An optional function to serialize the `value` before storing it in local\n   * storage.\n   *\n   * @defaultValue `JSON.stringify`\n   */\n  serializer?: StorageSerializer<T>;\n\n  /**\n   * An optional function to deserialize the `value` if the item existed in\n   * local storage.\n   *\n   * @defaultValue `JSON.parse`\n   */\n  deserializer?: StorageDeserializer<T>;\n}\n\n/** @since 6.0.0 */\nexport interface StorageOptions<T> extends StorageSerializers<T> {\n  /**\n   * The storage key name to use. This can be set to an empty string for\n   * internal usage of conditionally saving items to storage.\n   */\n  key: string;\n\n  /**\n   * The default value to use if an item does not exist in storage.\n   */\n  defaultValue: UseStateInitializer<T>;\n\n  /**\n   * Set this to `true` to update:\n   *\n   * - the default {@link serializer} to be:\n   * ```\n   * typeof value === \"string\" ? value : `${value}`\n   * ```\n   * - the default {@link deserializer} to not call `JSON.parse` if the\n   *   {@link defaultValue} is a string.\n   *\n   * @defaultValue `typeof defaultValue === 'string'`\n   */\n  raw?: boolean;\n\n  /**\n   * Set this to `true` to require a manual `persist()` or `remove()` call\n   * to update the storage value.\n   *\n   * @defaultValue `false`\n   */\n  manual?: boolean;\n\n  /** @defaultValue `globalThis.localStorage` */\n  storage?: Storage;\n}\n\n/** @since 6.0.0 */\nexport interface StorageImplementation<T> {\n  value: T;\n\n  /**\n   * Updates the {@link value} in state. When the\n   * {@link StorageOptions.manual} option is `false`, the value will\n   * also be updated in local storage immediately.\n   */\n  setValue: UseStateSetter<T>;\n\n  /**\n   * Remove the item from local storage.\n   */\n  remove: () => void;\n\n  /**\n   * Manually persist the current {@link value} into local storage. This is only\n   * useful if the {@link StorageOptions.manual} option is `true`.\n   */\n  persist: () => void;\n}\n"],"names":[],"mappings":"AAkEA,iBAAiB,GACjB,WAoBC"}

package/dist/storage/useStorage.d.ts

@@ -0,0 +1,113 @@
+import { type StorageImplementation, type StorageOptions } from "./types.js";
+/**
+ * The `useStorage` hook can be used to read and write from `localStorage`
+ * (default) or `sessionStorage`. The default behavior will automatically sync
+ * the value across tabs using the `StorageEvent`.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useStorage } from "@react-md/core/storage/useStorage";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { value, setValue } = useStorage({
+ *     key: "savedSearch",
+ *     defaultValue: "",
+ *   });
+ *
+ *   return (
+ *     <TextField
+ *       label="Search"
+ *       placeholder="Search..."
+ *       type="search"
+ *       value={value}
+ *       onChange={(event) => {
+ *         setValue(event.currentTarget.value)
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example Type-safe Objects
+ * ```tsx
+ * import { useStorage } from "@react-md/core/storage/useStorage";
+ * import { type ReactElement } from "react";
+ *
+ * interface ExpectedSchema {
+ *   label: string;
+ *   value: string;
+ *   // others
+ * }
+ *
+ * function Example(): ReactElement {
+ *   const { value, setValue } = useStorage<ExpectedSchema | null>({
+ *     key: "someKey",
+ *     defaultValue: null,
+ *
+ *     // this is optional: you can create a custom deserializer to validate
+ *     // the stored value to prevent people manually updating local storage in
+ *     // the dev tools
+ *     deserializer(item) {
+ *       const parsed = JSON.parse(item):
+ *       const { label, value } = parsed;
+ *       if (typeof label !== 'string' || typeof value !== 'string') {
+ *         return null;
+ *       }
+ *
+ *       return { label, value };
+ *     }
+ *   });
+ *
+ *   // do something
+ *   // value will be `ExpectedSchema | null`
+ * }
+ * ```
+ *
+ * @example Manual Persistence
+ * ```tsx
+ * import { Button } from "@react-md/core/button/Button";
+ * import { Checkbox } from "@react-md/core/form/Checkbox";
+ * import { Form } from "@react-md/core/form/Form";
+ * import { useStorage } from "@react-md/core/storage/useStorage";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { value, setValue, remove, persist } = useStorage({
+ *     key: "someKey",
+ *     manual: true,
+ *     defaultValue: false,
+ *   });
+ *
+ *   return (
+ *     <Form
+ *       onSubmit={() => {
+ *         // current value will be saved into local storage
+ *         persist();
+ *       }}
+ *       onReset={() => {
+ *         // "someKey" will be removed from local storage
+ *         remove();
+ *       }}
+ *     >
+ *       <Checkbox
+ *         label="Allow cookies"
+ *         checked={value}
+ *         onChange={(event) =>
+ *           setValue(event.currentTarget.checked);
+ *         }
+ *       />
+ *       <Button type="reset">Decline</Button>
+ *       <Button type="submit">Save</Button>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/StorageEvent
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage
+ * @since 6.0.0
+ */
+export declare function useStorage<T>(options: StorageOptions<T>): StorageImplementation<T>;

package/dist/storage/useStorage.js

@@ -0,0 +1,247 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useSsr } from "../SsrProvider.js";
+import { useIsomorphicLayoutEffect } from "../useIsomorphicLayoutEffect.js";
+import { getStorageSerializers } from "./internalUtils.js";
+import { getItemFromStorage, removeItemFromStorage, setItemInStorage } from "./utils.js";
+/**
+ * The `useStorage` hook can be used to read and write from `localStorage`
+ * (default) or `sessionStorage`. The default behavior will automatically sync
+ * the value across tabs using the `StorageEvent`.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useStorage } from "@react-md/core/storage/useStorage";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { value, setValue } = useStorage({
+ *     key: "savedSearch",
+ *     defaultValue: "",
+ *   });
+ *
+ *   return (
+ *     <TextField
+ *       label="Search"
+ *       placeholder="Search..."
+ *       type="search"
+ *       value={value}
+ *       onChange={(event) => {
+ *         setValue(event.currentTarget.value)
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example Type-safe Objects
+ * ```tsx
+ * import { useStorage } from "@react-md/core/storage/useStorage";
+ * import { type ReactElement } from "react";
+ *
+ * interface ExpectedSchema {
+ *   label: string;
+ *   value: string;
+ *   // others
+ * }
+ *
+ * function Example(): ReactElement {
+ *   const { value, setValue } = useStorage<ExpectedSchema | null>({
+ *     key: "someKey",
+ *     defaultValue: null,
+ *
+ *     // this is optional: you can create a custom deserializer to validate
+ *     // the stored value to prevent people manually updating local storage in
+ *     // the dev tools
+ *     deserializer(item) {
+ *       const parsed = JSON.parse(item):
+ *       const { label, value } = parsed;
+ *       if (typeof label !== 'string' || typeof value !== 'string') {
+ *         return null;
+ *       }
+ *
+ *       return { label, value };
+ *     }
+ *   });
+ *
+ *   // do something
+ *   // value will be `ExpectedSchema | null`
+ * }
+ * ```
+ *
+ * @example Manual Persistence
+ * ```tsx
+ * import { Button } from "@react-md/core/button/Button";
+ * import { Checkbox } from "@react-md/core/form/Checkbox";
+ * import { Form } from "@react-md/core/form/Form";
+ * import { useStorage } from "@react-md/core/storage/useStorage";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { value, setValue, remove, persist } = useStorage({
+ *     key: "someKey",
+ *     manual: true,
+ *     defaultValue: false,
+ *   });
+ *
+ *   return (
+ *     <Form
+ *       onSubmit={() => {
+ *         // current value will be saved into local storage
+ *         persist();
+ *       }}
+ *       onReset={() => {
+ *         // "someKey" will be removed from local storage
+ *         remove();
+ *       }}
+ *     >
+ *       <Checkbox
+ *         label="Allow cookies"
+ *         checked={value}
+ *         onChange={(event) =>
+ *           setValue(event.currentTarget.checked);
+ *         }
+ *       />
+ *       <Button type="reset">Decline</Button>
+ *       <Button type="submit">Save</Button>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/StorageEvent
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage
+ * @since 6.0.0
+ */ export function useStorage(options) {
+    const { key, defaultValue, manual, storage = globalThis.localStorage } = options;
+    const [initialValue] = useState(defaultValue);
+    const { serializer, deserializer } = useMemo(()=>getStorageSerializers({
+            raw: options.raw,
+            serializer: options.serializer,
+            deserializer: options.deserializer,
+            initialValue
+        }), [
+        initialValue,
+        options.deserializer,
+        options.raw,
+        options.serializer
+    ]);
+    const ssr = useSsr();
+    const [value, setStoredValue] = useState(()=>{
+        if (ssr) {
+            return initialValue;
+        }
+        return getItemFromStorage({
+            key,
+            storage,
+            fallback: initialValue,
+            deserializer
+        });
+    });
+    const config = useRef({
+        key,
+        value,
+        manual,
+        storage,
+        serializer,
+        deserializer,
+        defaultValue: initialValue
+    });
+    useIsomorphicLayoutEffect(()=>{
+        config.current = {
+            key,
+            value,
+            manual,
+            storage,
+            serializer,
+            deserializer,
+            defaultValue: initialValue
+        };
+    });
+    const setValue = useCallback((valueOrDispatcher)=>{
+        const { key, manual, storage, serializer } = config.current;
+        setStoredValue((prevValue)=>{
+            const nextValue = valueOrDispatcher instanceof Function ? valueOrDispatcher(prevValue) : valueOrDispatcher;
+            if (!manual && nextValue !== prevValue) {
+                setItemInStorage({
+                    key,
+                    value: nextValue,
+                    storage,
+                    serializer
+                });
+            }
+            return nextValue;
+        });
+    }, []);
+    const remove = useCallback(()=>{
+        removeItemFromStorage(config.current);
+    }, []);
+    const persist = useCallback(()=>{
+        setItemInStorage(config.current);
+    }, []);
+    // make sure to sync the value in local storage
+    useEffect(()=>{
+        const { value, manual, storage, serializer } = config.current;
+        if (ssr || !key || !value || manual || !storage) {
+            return;
+        }
+        setItemInStorage({
+            key,
+            value,
+            storage,
+            serializer
+        });
+    }, [
+        key,
+        ssr
+    ]);
+    useEffect(()=>{
+        const { defaultValue, storage, deserializer, manual } = config.current;
+        if (manual || !ssr) {
+            return;
+        }
+        // do not want to trigger the emit behavior for rehydration
+        setStoredValue(getItemFromStorage({
+            key,
+            storage,
+            fallback: defaultValue,
+            deserializer
+        }));
+    }, [
+        key,
+        ssr
+    ]);
+    // update the value if another tab changed the local storage value
+    useEffect(()=>{
+        if (!key) {
+            return;
+        }
+        const callback = (event)=>{
+            const { storage, defaultValue, deserializer } = config.current;
+            if (event.key === key && event.storageArea === storage) {
+                setStoredValue(getItemFromStorage({
+                    key,
+                    storage,
+                    fallback: defaultValue,
+                    deserializer
+                }));
+            }
+        };
+        window.addEventListener("storage", callback);
+        return ()=>{
+            window.removeEventListener("storage", callback);
+        };
+    }, [
+        key
+    ]);
+    return {
+        value,
+        setValue,
+        remove,
+        persist
+    };
+}
+
+//# sourceMappingURL=useStorage.js.map

package/dist/storage/useStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/storage/useStorage.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\n\nimport { useSsr } from \"../SsrProvider.js\";\nimport { type UseStateSetter } from \"../types.js\";\nimport { useIsomorphicLayoutEffect } from \"../useIsomorphicLayoutEffect.js\";\nimport { getStorageSerializers } from \"./internalUtils.js\";\nimport { type StorageImplementation, type StorageOptions } from \"./types.js\";\nimport {\n  getItemFromStorage,\n  removeItemFromStorage,\n  setItemInStorage,\n} from \"./utils.js\";\n\n/**\n * The `useStorage` hook can be used to read and write from `localStorage`\n * (default) or `sessionStorage`. The default behavior will automatically sync\n * the value across tabs using the `StorageEvent`.\n *\n * @example Simple Example\n * ```tsx\n * import { TextField } from \"@react-md/core/form/TextField\";\n * import { useStorage } from \"@react-md/core/storage/useStorage\";\n * import { type ReactElement } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { value, setValue } = useStorage({\n *     key: \"savedSearch\",\n *     defaultValue: \"\",\n *   });\n *\n *   return (\n *     <TextField\n *       label=\"Search\"\n *       placeholder=\"Search...\"\n *       type=\"search\"\n *       value={value}\n *       onChange={(event) => {\n *         setValue(event.currentTarget.value)\n *       }}\n *     />\n *   );\n * }\n * ```\n *\n * @example Type-safe Objects\n * ```tsx\n * import { useStorage } from \"@react-md/core/storage/useStorage\";\n * import { type ReactElement } from \"react\";\n *\n * interface ExpectedSchema {\n *   label: string;\n *   value: string;\n *   // others\n * }\n *\n * function Example(): ReactElement {\n *   const { value, setValue } = useStorage<ExpectedSchema | null>({\n *     key: \"someKey\",\n *     defaultValue: null,\n *\n *     // this is optional: you can create a custom deserializer to validate\n *     // the stored value to prevent people manually updating local storage in\n *     // the dev tools\n *     deserializer(item) {\n *       const parsed = JSON.parse(item):\n *       const { label, value } = parsed;\n *       if (typeof label !== 'string' || typeof value !== 'string') {\n *         return null;\n *       }\n *\n *       return { label, value };\n *     }\n *   });\n *\n *   // do something\n *   // value will be `ExpectedSchema | null`\n * }\n * ```\n *\n * @example Manual Persistence\n * ```tsx\n * import { Button } from \"@react-md/core/button/Button\";\n * import { Checkbox } from \"@react-md/core/form/Checkbox\";\n * import { Form } from \"@react-md/core/form/Form\";\n * import { useStorage } from \"@react-md/core/storage/useStorage\";\n * import { type ReactElement } from \"react\";\n *\n * function Example(): ReactElement {\n *   const { value, setValue, remove, persist } = useStorage({\n *     key: \"someKey\",\n *     manual: true,\n *     defaultValue: false,\n *   });\n *\n *   return (\n *     <Form\n *       onSubmit={() => {\n *         // current value will be saved into local storage\n *         persist();\n *       }}\n *       onReset={() => {\n *         // \"someKey\" will be removed from local storage\n *         remove();\n *       }}\n *     >\n *       <Checkbox\n *         label=\"Allow cookies\"\n *         checked={value}\n *         onChange={(event) =>\n *           setValue(event.currentTarget.checked);\n *         }\n *       />\n *       <Button type=\"reset\">Decline</Button>\n *       <Button type=\"submit\">Save</Button>\n *     </Form>\n *   );\n * }\n * ```\n *\n * @see https://developer.mozilla.org/en-US/docs/Web/API/StorageEvent\n * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage\n * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage\n * @since 6.0.0\n */\nexport function useStorage<T>(\n  options: StorageOptions<T>\n): StorageImplementation<T> {\n  const {\n    key,\n    defaultValue,\n    manual,\n    storage = globalThis.localStorage,\n  } = options;\n\n  const [initialValue] = useState(defaultValue);\n  const { serializer, deserializer } = useMemo(\n    () =>\n      getStorageSerializers({\n        raw: options.raw,\n        serializer: options.serializer,\n        deserializer: options.deserializer,\n        initialValue,\n      }),\n    [initialValue, options.deserializer, options.raw, options.serializer]\n  );\n\n  const ssr = useSsr();\n  const [value, setStoredValue] = useState<T>(() => {\n    if (ssr) {\n      return initialValue;\n    }\n\n    return getItemFromStorage({\n      key,\n      storage,\n      fallback: initialValue,\n      deserializer,\n    });\n  });\n\n  const config = useRef({\n    key,\n    value,\n    manual,\n    storage,\n    serializer,\n    deserializer,\n    defaultValue: initialValue,\n  } as const);\n  useIsomorphicLayoutEffect(() => {\n    config.current = {\n      key,\n      value,\n      manual,\n      storage,\n      serializer,\n      deserializer,\n      defaultValue: initialValue,\n    };\n  });\n\n  const setValue = useCallback<UseStateSetter<T>>((valueOrDispatcher) => {\n    const { key, manual, storage, serializer } = config.current;\n\n    setStoredValue((prevValue) => {\n      const nextValue =\n        valueOrDispatcher instanceof Function\n          ? valueOrDispatcher(prevValue)\n          : valueOrDispatcher;\n\n      if (!manual && nextValue !== prevValue) {\n        setItemInStorage({\n          key,\n          value: nextValue,\n          storage,\n          serializer,\n        });\n      }\n\n      return nextValue;\n    });\n  }, []);\n\n  const remove = useCallback(() => {\n    removeItemFromStorage(config.current);\n  }, []);\n\n  const persist = useCallback(() => {\n    setItemInStorage(config.current);\n  }, []);\n\n  // make sure to sync the value in local storage\n  useEffect(() => {\n    const { value, manual, storage, serializer } = config.current;\n    if (ssr || !key || !value || manual || !storage) {\n      return;\n    }\n\n    setItemInStorage({\n      key,\n      value,\n      storage,\n      serializer,\n    });\n  }, [key, ssr]);\n  useEffect(() => {\n    const { defaultValue, storage, deserializer, manual } = config.current;\n    if (manual || !ssr) {\n      return;\n    }\n\n    // do not want to trigger the emit behavior for rehydration\n    setStoredValue(\n      getItemFromStorage({\n        key,\n        storage,\n        fallback: defaultValue,\n        deserializer,\n      })\n    );\n  }, [key, ssr]);\n\n  // update the value if another tab changed the local storage value\n  useEffect(() => {\n    if (!key) {\n      return;\n    }\n\n    const callback = (event: StorageEvent): void => {\n      const { storage, defaultValue, deserializer } = config.current;\n      if (event.key === key && event.storageArea === storage) {\n        setStoredValue(\n          getItemFromStorage({\n            key,\n            storage,\n            fallback: defaultValue,\n            deserializer,\n          })\n        );\n      }\n    };\n\n    window.addEventListener(\"storage\", callback);\n    return () => {\n      window.removeEventListener(\"storage\", callback);\n    };\n  }, [key]);\n\n  return {\n    value,\n    setValue,\n    remove,\n    persist,\n  };\n}\n"],"names":["useCallback","useEffect","useMemo","useRef","useState","useSsr","useIsomorphicLayoutEffect","getStorageSerializers","getItemFromStorage","removeItemFromStorage","setItemInStorage","useStorage","options","key","defaultValue","manual","storage","globalThis","localStorage","initialValue","serializer","deserializer","raw","ssr","value","setStoredValue","fallback","config","current","setValue","valueOrDispatcher","prevValue","nextValue","Function","remove","persist","callback","event","storageArea","window","addEventListener","removeEventListener"],"mappings":"AAAA;AAEA,SAASA,WAAW,EAAEC,SAAS,EAAEC,OAAO,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,QAAQ;AAE1E,SAASC,MAAM,QAAQ,oBAAoB;AAE3C,SAASC,yBAAyB,QAAQ,kCAAkC;AAC5E,SAASC,qBAAqB,QAAQ,qBAAqB;AAE3D,SACEC,kBAAkB,EAClBC,qBAAqB,EACrBC,gBAAgB,QACX,aAAa;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8GC,GACD,OAAO,SAASC,WACdC,OAA0B;IAE1B,MAAM,EACJC,GAAG,EACHC,YAAY,EACZC,MAAM,EACNC,UAAUC,WAAWC,YAAY,EAClC,GAAGN;IAEJ,MAAM,CAACO,aAAa,GAAGf,SAASU;IAChC,MAAM,EAAEM,UAAU,EAAEC,YAAY,EAAE,GAAGnB,QACnC,IACEK,sBAAsB;YACpBe,KAAKV,QAAQU,GAAG;YAChBF,YAAYR,QAAQQ,UAAU;YAC9BC,cAAcT,QAAQS,YAAY;YAClCF;QACF,IACF;QAACA;QAAcP,QAAQS,YAAY;QAAET,QAAQU,GAAG;QAAEV,QAAQQ,UAAU;KAAC;IAGvE,MAAMG,MAAMlB;IACZ,MAAM,CAACmB,OAAOC,eAAe,GAAGrB,SAAY;QAC1C,IAAImB,KAAK;YACP,OAAOJ;QACT;QAEA,OAAOX,mBAAmB;YACxBK;YACAG;YACAU,UAAUP;YACVE;QACF;IACF;IAEA,MAAMM,SAASxB,OAAO;QACpBU;QACAW;QACAT;QACAC;QACAI;QACAC;QACAP,cAAcK;IAChB;IACAb,0BAA0B;QACxBqB,OAAOC,OAAO,GAAG;YACff;YACAW;YACAT;YACAC;YACAI;YACAC;YACAP,cAAcK;QAChB;IACF;IAEA,MAAMU,WAAW7B,YAA+B,CAAC8B;QAC/C,MAAM,EAAEjB,GAAG,EAAEE,MAAM,EAAEC,OAAO,EAAEI,UAAU,EAAE,GAAGO,OAAOC,OAAO;QAE3DH,eAAe,CAACM;YACd,MAAMC,YACJF,6BAA6BG,WACzBH,kBAAkBC,aAClBD;YAEN,IAAI,CAACf,UAAUiB,cAAcD,WAAW;gBACtCrB,iBAAiB;oBACfG;oBACAW,OAAOQ;oBACPhB;oBACAI;gBACF;YACF;YAEA,OAAOY;QACT;IACF,GAAG,EAAE;IAEL,MAAME,SAASlC,YAAY;QACzBS,sBAAsBkB,OAAOC,OAAO;IACtC,GAAG,EAAE;IAEL,MAAMO,UAAUnC,YAAY;QAC1BU,iBAAiBiB,OAAOC,OAAO;IACjC,GAAG,EAAE;IAEL,+CAA+C;IAC/C3B,UAAU;QACR,MAAM,EAAEuB,KAAK,EAAET,MAAM,EAAEC,OAAO,EAAEI,UAAU,EAAE,GAAGO,OAAOC,OAAO;QAC7D,IAAIL,OAAO,CAACV,OAAO,CAACW,SAAST,UAAU,CAACC,SAAS;YAC/C;QACF;QAEAN,iBAAiB;YACfG;YACAW;YACAR;YACAI;QACF;IACF,GAAG;QAACP;QAAKU;KAAI;IACbtB,UAAU;QACR,MAAM,EAAEa,YAAY,EAAEE,OAAO,EAAEK,YAAY,EAAEN,MAAM,EAAE,GAAGY,OAAOC,OAAO;QACtE,IAAIb,UAAU,CAACQ,KAAK;YAClB;QACF;QAEA,2DAA2D;QAC3DE,eACEjB,mBAAmB;YACjBK;YACAG;YACAU,UAAUZ;YACVO;QACF;IAEJ,GAAG;QAACR;QAAKU;KAAI;IAEb,kEAAkE;IAClEtB,UAAU;QACR,IAAI,CAACY,KAAK;YACR;QACF;QAEA,MAAMuB,WAAW,CAACC;YAChB,MAAM,EAAErB,OAAO,EAAEF,YAAY,EAAEO,YAAY,EAAE,GAAGM,OAAOC,OAAO;YAC9D,IAAIS,MAAMxB,GAAG,KAAKA,OAAOwB,MAAMC,WAAW,KAAKtB,SAAS;gBACtDS,eACEjB,mBAAmB;oBACjBK;oBACAG;oBACAU,UAAUZ;oBACVO;gBACF;YAEJ;QACF;QAEAkB,OAAOC,gBAAgB,CAAC,WAAWJ;QACnC,OAAO;YACLG,OAAOE,mBAAmB,CAAC,WAAWL;QACxC;IACF,GAAG;QAACvB;KAAI;IAER,OAAO;QACLW;QACAK;QACAK;QACAC;IACF;AACF"}

package/dist/storage/utils.d.ts

@@ -0,0 +1,94 @@
+import { type StorageDeserializer, type StorageOptions, type StorageSerializer } from "./types.js";
+/** @since 6.0.0 */
+export type ModifyStorageOptions = Pick<StorageOptions<unknown>, "key" | "storage">;
+/** @since 6.0.0 */
+export interface GetItemFromStorageOptions<T> extends ModifyStorageOptions {
+    /**
+     * A value to use when the {@link key} does not exist in storage or there is
+     * an error deserializing the value.
+     */
+    fallback: T;
+    /** @see {@link StorageOptions.deserializer} */
+    deserializer?: StorageDeserializer<T>;
+}
+/**
+ * This is a low-level helper function get a value from storage (defaults to
+ * `localStorage`). You'll most likely want to use a pre-built implementation
+ * like `useStorage` instead.
+ *
+ * @example
+ * ```ts
+ * import { getItemFromStorage } from "@react-md/core/storage/utils";
+ *
+ * const values = ["a", "b", "c", "d"] as const;
+ *
+ * const item1 = getItemFromStorage({
+ *   key: "testKey",
+ *   fallback: values[0],
+ *   deserializer(item) {
+ *     if (!values.includes(item)) {
+ *       return values[0]
+ *     }
+ *
+ *     return item;
+ *   },
+ * });
+ *
+ * const item2 = getItemFromStorage({
+ *   key: "anotherKey",
+ *   fallback: -1,
+ * });
+ *
+ * const item3 = getItemFromStorage({
+ *   key: "anotherKey",
+ *   fallback: -1,
+ *   storage: sessionStorage,
+ * });
+ * ```
+ *
+ * @since 6.0.0
+ */
+export declare function getItemFromStorage<T>(options: GetItemFromStorageOptions<T>): T;
+/** @since 6.0.0 */
+export interface SetItemInStorageOptions<T> extends ModifyStorageOptions {
+    value: T;
+    /** @see {@link StorageOptions.serializer} */
+    serializer?: StorageSerializer<T>;
+}
+/**
+ * You'll most likely want to use `useStorage` instead, but this is a low-level
+ * util to "safely" set an item in `localStorage` or `sessionStorage`.
+ *
+ * @example
+ * ```ts
+ * import { setItemFromStorage } from "@react-md/core/storage/utils";
+ * import { identity } from "@react-md/core/utils/identity";
+ *
+ * const values = ["a", "b", "c", "d"] as const;
+ *
+ * setItemInStorage({
+ *   key: "testKey",
+ *   value: values[0],
+ *   // store string value as-is
+ *   serializer: identity,
+ * });
+ *
+ * setItemInStorage({
+ *   key: "anotherKey",
+ *   value: 100,
+ * });
+ *
+ * setItemInStorage({
+ *   key: "anotherKey",
+ *   value: 100,
+ *   storage: sessionStorage,
+ * });
+ * ```
+ *
+ * @since 6.0.0
+ */
+export declare function setItemInStorage<T>(options: SetItemInStorageOptions<T>): void;
+/**
+ * @since 6.0.0
+ */
+export declare function removeItemFromStorage(options: ModifyStorageOptions): void;