@live-favicon/react 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @live-favicon/react
+
+React hooks for [live-favicon](https://www.npmjs.com/package/@live-favicon/core) — turn the browser tab into a live status indicator.
+
+## Install
+
+```bash
+npm install @live-favicon/core @live-favicon/react
+```
+
+## `useFaviconState`
+
+Drives the favicon from a piece of React state. Resets on unmount by default.
+
+```tsx
+import { useFaviconState } from "@live-favicon/react";
+
+function GenerationStatus({ status }: { status: "pending" | "done" | "failed" }) {
+  useFaviconState(status === "pending" ? "thinking" : status === "done" ? "success" : "error");
+  return null;
+}
+```
+
+## `useFaviconTask`
+
+Runs an async factory whenever `deps` change, driving the favicon through its
+task lifecycle automatically, and returns `{ data, error, status }`.
+
+```tsx
+import { useFaviconTask } from "@live-favicon/react";
+
+function SearchResults({ query }: { query: string }) {
+  const { status, data, error } = useFaviconTask(
+    () => (query ? fetchResults(query) : null),
+    [query],
+  );
+
+  if (status === "pending") return <p>Loading...</p>;
+  if (status === "error") return <p>Failed: {String(error)}</p>;
+  return <ResultsList results={data} />;
+}
+```
+
+## Imperative escape hatch
+
+The underlying singleton and all of core's types are re-exported, for anything
+outside a component (event handlers, non-React code):
+
+```tsx
+import { favicon } from "@live-favicon/react";
+
+async function onExport() {
+  await favicon.task(exportReport());
+}
+```
+
+See the [live-favicon README](https://github.com/cridorainfo/live-favicon#readme) for the full state list and API.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";var U=Object.create;var i=Object.defineProperty;var x=Object.getOwnPropertyDescriptor;var O=Object.getOwnPropertyNames;var y=Object.getPrototypeOf,R=Object.prototype.hasOwnProperty;var E=(e,t)=>{for(var n in t)i(e,n,{get:t[n],enumerable:!0})},l=(e,t,n,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of O(t))!R.call(e,o)&&o!==n&&i(e,o,{get:()=>t[o],enumerable:!(s=x(t,o))||s.enumerable});return e};var p=(e,t,n)=>(n=e!=null?U(y(e)):{},l(t||!e||!e.__esModule?i(n,"default",{value:e,enumerable:!0}):n,e)),g=e=>l(i({},"__esModule",{value:!0}),e);var h={};E(h,{FAVICON_SIZE:()=>c.FAVICON_SIZE,favicon:()=>c.default,useFaviconState:()=>T,useFaviconTask:()=>S});module.exports=g(h);var c=p(require("@live-favicon/core"),1);var a=require("react"),d=p(require("@live-favicon/core"),1);function T(e,t={}){let{resetOnUnmount:n=!0}=t,s=(0,a.useRef)(n);s.current=n,(0,a.useEffect)(()=>{e&&d.default.state(e)},[e]),(0,a.useEffect)(()=>()=>{s.current&&d.default.reset()},[])}var r=require("react"),k=p(require("@live-favicon/core"),1);function S(e,t,n){let[s,o]=(0,r.useState)({data:void 0,error:void 0,status:"idle"}),v=(0,r.useRef)(e);v.current=e;let m=(0,r.useRef)(n);return m.current=n,(0,r.useEffect)(()=>{let F=v.current();if(!F)return;let u=!1;return o({data:void 0,error:void 0,status:"pending"}),k.default.task(F,m.current).then(f=>{u||o({data:f,error:void 0,status:"success"})}).catch(f=>{u||o({data:void 0,error:f,status:"error"})}),()=>{u=!0}},t),s}0&&(module.exports={FAVICON_SIZE,favicon,useFaviconState,useFaviconTask});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useFaviconState.ts","../src/useFaviconTask.ts"],"sourcesContent":["export { default as favicon, FAVICON_SIZE } from \"@live-favicon/core\";\nexport type { FaviconState, TaskOptions } from \"@live-favicon/core\";\n\nexport { useFaviconState } from \"./useFaviconState\";\nexport type { UseFaviconStateOptions } from \"./useFaviconState\";\n\nexport { useFaviconTask } from \"./useFaviconTask\";\nexport type { UseFaviconTaskResult, UseFaviconTaskStatus } from \"./useFaviconTask\";\n","import { useEffect, useRef } from \"react\";\nimport favicon from \"@live-favicon/core\";\nimport type { FaviconState } from \"@live-favicon/core\";\n\nexport interface UseFaviconStateOptions {\n  /**\n   * Restore the page's original favicon and title when this component\n   * unmounts. Default: true. Since the favicon is a single, page-wide\n   * singleton, only set this to false if another part of the app is\n   * responsible for resetting it.\n   */\n  resetOnUnmount?: boolean;\n}\n\n/**\n * Drives the shared favicon singleton from a piece of React state.\n * Pass `null`/`undefined` to leave the favicon untouched — useful before a\n * state is known yet.\n *\n * @example\n * function GenerationStatus({ status }: { status: \"pending\" | \"done\" | \"failed\" }) {\n *   useFaviconState(\n *     status === \"pending\" ? \"thinking\" : status === \"done\" ? \"success\" : \"error\"\n *   );\n *   return null;\n * }\n */\nexport function useFaviconState(\n  state: FaviconState | null | undefined,\n  options: UseFaviconStateOptions = {},\n): void {\n  const { resetOnUnmount = true } = options;\n  const resetOnUnmountRef = useRef(resetOnUnmount);\n  resetOnUnmountRef.current = resetOnUnmount;\n\n  useEffect(() => {\n    if (state) favicon.state(state);\n  }, [state]);\n\n  useEffect(() => {\n    return () => {\n      if (resetOnUnmountRef.current) favicon.reset();\n    };\n  }, []);\n}\n","import { useEffect, useRef, useState, type DependencyList } from \"react\";\nimport favicon from \"@live-favicon/core\";\nimport type { TaskOptions } from \"@live-favicon/core\";\n\nexport type UseFaviconTaskStatus = \"idle\" | \"pending\" | \"success\" | \"error\";\n\nexport interface UseFaviconTaskResult<T> {\n  data: T | undefined;\n  error: unknown;\n  status: UseFaviconTaskStatus;\n}\n\n/**\n * Runs `factory()` whenever `deps` change, driving the favicon through its\n * task lifecycle (start -> success/error) for the duration. Returning `null`\n * from `factory` skips the run — e.g. while required inputs aren't ready.\n *\n * @example\n * const { status, data } = useFaviconTask(\n *   () => (query ? fetchResults(query) : null),\n *   [query]\n * );\n */\nexport function useFaviconTask<T>(\n  factory: () => Promise<T> | null,\n  deps: DependencyList,\n  options?: TaskOptions,\n): UseFaviconTaskResult<T> {\n  const [state, setState] = useState<UseFaviconTaskResult<T>>({\n    data: undefined,\n    error: undefined,\n    status: \"idle\",\n  });\n\n  const factoryRef = useRef(factory);\n  factoryRef.current = factory;\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  useEffect(() => {\n    const promise = factoryRef.current();\n    if (!promise) return;\n\n    let cancelled = false;\n    setState({ data: undefined, error: undefined, status: \"pending\" });\n\n    favicon\n      .task(promise, optionsRef.current)\n      .then((data) => {\n        if (!cancelled) setState({ data, error: undefined, status: \"success\" });\n      })\n      .catch((error: unknown) => {\n        if (!cancelled) setState({ data: undefined, error, status: \"error\" });\n      });\n\n    return () => {\n      cancelled = true;\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, deps);\n\n  return state;\n}\n"],"mappings":"0jBAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,2EAAAE,EAAA,mBAAAC,IAAA,eAAAC,EAAAJ,GAAA,IAAAK,EAAiD,mCCAjD,IAAAC,EAAkC,iBAClCC,EAAoB,mCA0Bb,SAASC,EACdC,EACAC,EAAkC,CAAC,EAC7B,CACN,GAAM,CAAE,eAAAC,EAAiB,EAAK,EAAID,EAC5BE,KAAoB,UAAOD,CAAc,EAC/CC,EAAkB,QAAUD,KAE5B,aAAU,IAAM,CACVF,GAAO,EAAAI,QAAQ,MAAMJ,CAAK,CAChC,EAAG,CAACA,CAAK,CAAC,KAEV,aAAU,IACD,IAAM,CACPG,EAAkB,SAAS,EAAAC,QAAQ,MAAM,CAC/C,EACC,CAAC,CAAC,CACP,CC5CA,IAAAC,EAAiE,iBACjEC,EAAoB,mCAsBb,SAASC,EACdC,EACAC,EACAC,EACyB,CACzB,GAAM,CAACC,EAAOC,CAAQ,KAAI,YAAkC,CAC1D,KAAM,OACN,MAAO,OACP,OAAQ,MACV,CAAC,EAEKC,KAAa,UAAOL,CAAO,EACjCK,EAAW,QAAUL,EACrB,IAAMM,KAAa,UAAOJ,CAAO,EACjC,OAAAI,EAAW,QAAUJ,KAErB,aAAU,IAAM,CACd,IAAMK,EAAUF,EAAW,QAAQ,EACnC,GAAI,CAACE,EAAS,OAEd,IAAIC,EAAY,GAChB,OAAAJ,EAAS,CAAE,KAAM,OAAW,MAAO,OAAW,OAAQ,SAAU,CAAC,EAEjE,EAAAK,QACG,KAAKF,EAASD,EAAW,OAAO,EAChC,KAAMI,GAAS,CACTF,GAAWJ,EAAS,CAAE,KAAAM,EAAM,MAAO,OAAW,OAAQ,SAAU,CAAC,CACxE,CAAC,EACA,MAAOC,GAAmB,CACpBH,GAAWJ,EAAS,CAAE,KAAM,OAAW,MAAAO,EAAO,OAAQ,OAAQ,CAAC,CACtE,CAAC,EAEI,IAAM,CACXH,EAAY,EACd,CAEF,EAAGP,CAAI,EAEAE,CACT","names":["src_exports","__export","useFaviconState","useFaviconTask","__toCommonJS","import_core","import_react","import_core","useFaviconState","state","options","resetOnUnmount","resetOnUnmountRef","favicon","import_react","import_core","useFaviconTask","factory","deps","options","state","setState","factoryRef","optionsRef","promise","cancelled","favicon","data","error"]}

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+import { FaviconState, TaskOptions } from '@live-favicon/core';
+export { FAVICON_SIZE, FaviconState, TaskOptions, default as favicon } from '@live-favicon/core';
+import { DependencyList } from 'react';
+
+interface UseFaviconStateOptions {
+    /**
+     * Restore the page's original favicon and title when this component
+     * unmounts. Default: true. Since the favicon is a single, page-wide
+     * singleton, only set this to false if another part of the app is
+     * responsible for resetting it.
+     */
+    resetOnUnmount?: boolean;
+}
+/**
+ * Drives the shared favicon singleton from a piece of React state.
+ * Pass `null`/`undefined` to leave the favicon untouched — useful before a
+ * state is known yet.
+ *
+ * @example
+ * function GenerationStatus({ status }: { status: "pending" | "done" | "failed" }) {
+ *   useFaviconState(
+ *     status === "pending" ? "thinking" : status === "done" ? "success" : "error"
+ *   );
+ *   return null;
+ * }
+ */
+declare function useFaviconState(state: FaviconState | null | undefined, options?: UseFaviconStateOptions): void;
+
+type UseFaviconTaskStatus = "idle" | "pending" | "success" | "error";
+interface UseFaviconTaskResult<T> {
+    data: T | undefined;
+    error: unknown;
+    status: UseFaviconTaskStatus;
+}
+/**
+ * Runs `factory()` whenever `deps` change, driving the favicon through its
+ * task lifecycle (start -> success/error) for the duration. Returning `null`
+ * from `factory` skips the run — e.g. while required inputs aren't ready.
+ *
+ * @example
+ * const { status, data } = useFaviconTask(
+ *   () => (query ? fetchResults(query) : null),
+ *   [query]
+ * );
+ */
+declare function useFaviconTask<T>(factory: () => Promise<T> | null, deps: DependencyList, options?: TaskOptions): UseFaviconTaskResult<T>;
+
+export { type UseFaviconStateOptions, type UseFaviconTaskResult, type UseFaviconTaskStatus, useFaviconState, useFaviconTask };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { FaviconState, TaskOptions } from '@live-favicon/core';
+export { FAVICON_SIZE, FaviconState, TaskOptions, default as favicon } from '@live-favicon/core';
+import { DependencyList } from 'react';
+
+interface UseFaviconStateOptions {
+    /**
+     * Restore the page's original favicon and title when this component
+     * unmounts. Default: true. Since the favicon is a single, page-wide
+     * singleton, only set this to false if another part of the app is
+     * responsible for resetting it.
+     */
+    resetOnUnmount?: boolean;
+}
+/**
+ * Drives the shared favicon singleton from a piece of React state.
+ * Pass `null`/`undefined` to leave the favicon untouched — useful before a
+ * state is known yet.
+ *
+ * @example
+ * function GenerationStatus({ status }: { status: "pending" | "done" | "failed" }) {
+ *   useFaviconState(
+ *     status === "pending" ? "thinking" : status === "done" ? "success" : "error"
+ *   );
+ *   return null;
+ * }
+ */
+declare function useFaviconState(state: FaviconState | null | undefined, options?: UseFaviconStateOptions): void;
+
+type UseFaviconTaskStatus = "idle" | "pending" | "success" | "error";
+interface UseFaviconTaskResult<T> {
+    data: T | undefined;
+    error: unknown;
+    status: UseFaviconTaskStatus;
+}
+/**
+ * Runs `factory()` whenever `deps` change, driving the favicon through its
+ * task lifecycle (start -> success/error) for the duration. Returning `null`
+ * from `factory` skips the run — e.g. while required inputs aren't ready.
+ *
+ * @example
+ * const { status, data } = useFaviconTask(
+ *   () => (query ? fetchResults(query) : null),
+ *   [query]
+ * );
+ */
+declare function useFaviconTask<T>(factory: () => Promise<T> | null, deps: DependencyList, options?: TaskOptions): UseFaviconTaskResult<T>;
+
+export { type UseFaviconStateOptions, type UseFaviconTaskResult, type UseFaviconTaskStatus, useFaviconState, useFaviconTask };

package/dist/index.js

@@ -0,0 +1,2 @@
+import{default as h,FAVICON_SIZE as w}from"@live-favicon/core";import{useEffect as f,useRef as v}from"react";import p from"@live-favicon/core";function m(e,o={}){let{resetOnUnmount:t=!0}=o,n=v(t);n.current=t,f(()=>{e&&p.state(e)},[e]),f(()=>()=>{n.current&&p.reset()},[])}import{useEffect as F,useRef as d,useState as l}from"react";import T from"@live-favicon/core";function k(e,o,t){let[n,s]=l({data:void 0,error:void 0,status:"idle"}),i=d(e);i.current=e;let c=d(t);return c.current=t,F(()=>{let u=i.current();if(!u)return;let r=!1;return s({data:void 0,error:void 0,status:"pending"}),T.task(u,c.current).then(a=>{r||s({data:a,error:void 0,status:"success"})}).catch(a=>{r||s({data:void 0,error:a,status:"error"})}),()=>{r=!0}},o),n}export{w as FAVICON_SIZE,h as favicon,m as useFaviconState,k as useFaviconTask};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/useFaviconState.ts","../src/useFaviconTask.ts"],"sourcesContent":["export { default as favicon, FAVICON_SIZE } from \"@live-favicon/core\";\nexport type { FaviconState, TaskOptions } from \"@live-favicon/core\";\n\nexport { useFaviconState } from \"./useFaviconState\";\nexport type { UseFaviconStateOptions } from \"./useFaviconState\";\n\nexport { useFaviconTask } from \"./useFaviconTask\";\nexport type { UseFaviconTaskResult, UseFaviconTaskStatus } from \"./useFaviconTask\";\n","import { useEffect, useRef } from \"react\";\nimport favicon from \"@live-favicon/core\";\nimport type { FaviconState } from \"@live-favicon/core\";\n\nexport interface UseFaviconStateOptions {\n  /**\n   * Restore the page's original favicon and title when this component\n   * unmounts. Default: true. Since the favicon is a single, page-wide\n   * singleton, only set this to false if another part of the app is\n   * responsible for resetting it.\n   */\n  resetOnUnmount?: boolean;\n}\n\n/**\n * Drives the shared favicon singleton from a piece of React state.\n * Pass `null`/`undefined` to leave the favicon untouched — useful before a\n * state is known yet.\n *\n * @example\n * function GenerationStatus({ status }: { status: \"pending\" | \"done\" | \"failed\" }) {\n *   useFaviconState(\n *     status === \"pending\" ? \"thinking\" : status === \"done\" ? \"success\" : \"error\"\n *   );\n *   return null;\n * }\n */\nexport function useFaviconState(\n  state: FaviconState | null | undefined,\n  options: UseFaviconStateOptions = {},\n): void {\n  const { resetOnUnmount = true } = options;\n  const resetOnUnmountRef = useRef(resetOnUnmount);\n  resetOnUnmountRef.current = resetOnUnmount;\n\n  useEffect(() => {\n    if (state) favicon.state(state);\n  }, [state]);\n\n  useEffect(() => {\n    return () => {\n      if (resetOnUnmountRef.current) favicon.reset();\n    };\n  }, []);\n}\n","import { useEffect, useRef, useState, type DependencyList } from \"react\";\nimport favicon from \"@live-favicon/core\";\nimport type { TaskOptions } from \"@live-favicon/core\";\n\nexport type UseFaviconTaskStatus = \"idle\" | \"pending\" | \"success\" | \"error\";\n\nexport interface UseFaviconTaskResult<T> {\n  data: T | undefined;\n  error: unknown;\n  status: UseFaviconTaskStatus;\n}\n\n/**\n * Runs `factory()` whenever `deps` change, driving the favicon through its\n * task lifecycle (start -> success/error) for the duration. Returning `null`\n * from `factory` skips the run — e.g. while required inputs aren't ready.\n *\n * @example\n * const { status, data } = useFaviconTask(\n *   () => (query ? fetchResults(query) : null),\n *   [query]\n * );\n */\nexport function useFaviconTask<T>(\n  factory: () => Promise<T> | null,\n  deps: DependencyList,\n  options?: TaskOptions,\n): UseFaviconTaskResult<T> {\n  const [state, setState] = useState<UseFaviconTaskResult<T>>({\n    data: undefined,\n    error: undefined,\n    status: \"idle\",\n  });\n\n  const factoryRef = useRef(factory);\n  factoryRef.current = factory;\n  const optionsRef = useRef(options);\n  optionsRef.current = options;\n\n  useEffect(() => {\n    const promise = factoryRef.current();\n    if (!promise) return;\n\n    let cancelled = false;\n    setState({ data: undefined, error: undefined, status: \"pending\" });\n\n    favicon\n      .task(promise, optionsRef.current)\n      .then((data) => {\n        if (!cancelled) setState({ data, error: undefined, status: \"success\" });\n      })\n      .catch((error: unknown) => {\n        if (!cancelled) setState({ data: undefined, error, status: \"error\" });\n      });\n\n    return () => {\n      cancelled = true;\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, deps);\n\n  return state;\n}\n"],"mappings":"AAAA,OAAoB,WAAXA,EAAoB,gBAAAC,MAAoB,qBCAjD,OAAS,aAAAC,EAAW,UAAAC,MAAc,QAClC,OAAOC,MAAa,qBA0Bb,SAASC,EACdC,EACAC,EAAkC,CAAC,EAC7B,CACN,GAAM,CAAE,eAAAC,EAAiB,EAAK,EAAID,EAC5BE,EAAoBN,EAAOK,CAAc,EAC/CC,EAAkB,QAAUD,EAE5BN,EAAU,IAAM,CACVI,GAAOF,EAAQ,MAAME,CAAK,CAChC,EAAG,CAACA,CAAK,CAAC,EAEVJ,EAAU,IACD,IAAM,CACPO,EAAkB,SAASL,EAAQ,MAAM,CAC/C,EACC,CAAC,CAAC,CACP,CC5CA,OAAS,aAAAM,EAAW,UAAAC,EAAQ,YAAAC,MAAqC,QACjE,OAAOC,MAAa,qBAsBb,SAASC,EACdC,EACAC,EACAC,EACyB,CACzB,GAAM,CAACC,EAAOC,CAAQ,EAAIP,EAAkC,CAC1D,KAAM,OACN,MAAO,OACP,OAAQ,MACV,CAAC,EAEKQ,EAAaT,EAAOI,CAAO,EACjCK,EAAW,QAAUL,EACrB,IAAMM,EAAaV,EAAOM,CAAO,EACjC,OAAAI,EAAW,QAAUJ,EAErBP,EAAU,IAAM,CACd,IAAMY,EAAUF,EAAW,QAAQ,EACnC,GAAI,CAACE,EAAS,OAEd,IAAIC,EAAY,GAChB,OAAAJ,EAAS,CAAE,KAAM,OAAW,MAAO,OAAW,OAAQ,SAAU,CAAC,EAEjEN,EACG,KAAKS,EAASD,EAAW,OAAO,EAChC,KAAMG,GAAS,CACTD,GAAWJ,EAAS,CAAE,KAAAK,EAAM,MAAO,OAAW,OAAQ,SAAU,CAAC,CACxE,CAAC,EACA,MAAOC,GAAmB,CACpBF,GAAWJ,EAAS,CAAE,KAAM,OAAW,MAAAM,EAAO,OAAQ,OAAQ,CAAC,CACtE,CAAC,EAEI,IAAM,CACXF,EAAY,EACd,CAEF,EAAGP,CAAI,EAEAE,CACT","names":["default","FAVICON_SIZE","useEffect","useRef","favicon","useFaviconState","state","options","resetOnUnmount","resetOnUnmountRef","useEffect","useRef","useState","favicon","useFaviconTask","factory","deps","options","state","setState","factoryRef","optionsRef","promise","cancelled","data","error"]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@live-favicon/react",
+  "version": "0.1.0",
+  "description": "React hooks for live-favicon.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "favicon",
+    "react",
+    "hooks",
+    "browser-tab",
+    "status"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cridorainfo/live-favicon.git",
+    "directory": "packages/react"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "dependencies": {
+    "@live-favicon/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.1",
+    "@types/react": "^18.3.12",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}