react-inlinesvg 4.2.0 → 4.3.0

package/README.md

@@ -1,6 +1,6 @@
 # react-inlinesvg
 
-[![NPM version](https://badge.fury.io/js/react-inlinesvg.svg)](https://www.npmjs.com/package/react-inlinesvg) [![CI](https://github.com/gilbarbara/react-inlinesvg/actions/workflows/main.yml/badge.svg)](https://github.com/gilbarbara/react-inlinesvg/actions/workflows/main.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=gilbarbara_react-inlinesvg&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=gilbarbara_react-inlinesvg) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=gilbarbara_react-inlinesvg&metric=coverage)](https://sonarcloud.io/summary/new_code?id=gilbarbara_react-inlinesvg)
+[![NPM version](https://badge.fury.io/js/react-inlinesvg.svg)](https://www.npmjs.com/package/react-inlinesvg) [![CI](https://github.com/gilbarbara/react-inlinesvg/actions/workflows/ci.yml/badge.svg)](https://github.com/gilbarbara/react-inlinesvg/actions/workflows/ci.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=gilbarbara_react-inlinesvg&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=gilbarbara_react-inlinesvg) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=gilbarbara_react-inlinesvg&metric=coverage)](https://sonarcloud.io/summary/new_code?id=gilbarbara_react-inlinesvg)
 
 Load inline, local, or remote SVGs in your React components.
 
@@ -11,8 +11,7 @@ View the [demo](https://codesandbox.io/s/github/gilbarbara/react-inlinesvg/tree/
 - 🏖 **Easy to use:** Just set the `src`
 - 🛠 **Flexible:** Personalize the options to fit your needs
 - ⚡️ **Smart:** Async requests will be cached.
-- 🚀 **SSR:** Render a loader until the DOM is available
-- 🟦 **Typescript:** Nicely typed
+- 🚀 **SSR:** Safe for server-side rendering
 
 ## Usage
 
@@ -23,14 +22,13 @@ npm i react-inlinesvg
 And import it into your code:
 
 ```tsx
-import React from 'react';
 import SVG from 'react-inlinesvg';
 
 export default function App() {
   return (
     <main>
       <SVG
-        src="https://cdn.svgporn.com/logos/react.svg"
+        src="https://cdn.svglogos.dev/logos/react.svg"
         width={128}
         height="auto"
         title="React"
@@ -42,12 +40,15 @@ export default function App() {
 
 ## Props
 
-**src** {string} - **required**.  
-The SVG file you want to load. It can be a require, URL, or a string (base64 or URL encoded).
-_If you are using create-react-app and your file resides in the `public` directory, you can use the path directly without require._
+**src** {string} - **required**.
+The SVG to load. It accepts:
 
-**baseURL** {string}  
-An URL to prefix each ID in case you use the `<base>` tag and `uniquifyIDs`.
+- A URL or path to an SVG file (absolute or relative, including from a bundler import)
+- A data URI (base64 or URL-encoded)
+- A raw SVG string
+
+**baseURL** {string}
+A URL to prepend to `url()` references inside the SVG when using `uniquifyIDs`. Required if your page uses an HTML `<base>` tag.
 
 **children** {ReactNode}  
 The fallback content in case of a fetch error or unsupported browser.
@@ -58,9 +59,8 @@ The fallback content in case of a fetch error or unsupported browser.
 </SVG>
 ```
 
-**cacheRequests** {boolean} ▶︎ `true`  
-Cache remote SVGs.  
-Starting in version 4.x, you can also cache the files permanently, read more [below](#caching).
+**cacheRequests** {boolean} ▶︎ `true`
+Cache remote SVGs in memory. When used with the [CacheProvider](#caching), requests are also persisted in the browser cache.
 
 **description** {string}  
 A description for your SVG. It will override an existing `<desc>` tag.
@@ -68,8 +68,8 @@ A description for your SVG. It will override an existing `<desc>` tag.
 **fetchOptions** {RequestInit}  
 Custom options for the [request](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request).
 
-**innerRef** {React.Ref}  
-Set a ref in SVGElement.  
+**innerRef** {React.Ref\<SVGElement | null>}
+Set a ref on the SVG element.  
 
 >The SVG is processed and parsed so the ref won't be set on the initial render.
 You can use the `onLoad` callback to get and use the ref instead.
@@ -92,22 +92,14 @@ This will receive a single argument with:
 }
 ```
 
-- or an `InlineSVGError`, which has the following properties:
-
-```typescript
-{
-  name: 'InlineSVGError';
-  data: object; // optional
-  message: string;
-}
-```
+- or an `Error` for issues like missing `src`, unsupported browser, or invalid SVG content.
 
 **onLoad** {function}.  
 A callback to be invoked upon successful load.  
 This will receive 2 arguments: the `src` prop and an `isCached` boolean
 
-**preProcessor** {function} ▶︎ `string`  
-A function to process the contents of the SVG text before parsing.
+**preProcessor** {function}
+A function to pre-process the SVG string before parsing. Receives the SVG string and must return a string.
 
 **title** {string | null}  
 A title for your SVG. It will override an existing `<title>` tag.  
@@ -123,7 +115,7 @@ Create unique IDs for each icon.
 
 ### Example
 
-```jsx
+```tsx
 <SVG
   baseURL="/home"
   cacheRequests={true}
@@ -132,7 +124,7 @@ Create unique IDs for each icon.
   onError={(error) => console.log(error.message)}
   onLoad={(src, isCached) => console.log(src, isCached)}
   preProcessor={(code) => code.replace(/fill=".*?"/g, 'fill="currentColor"')}
-  src="https://cdn.svgporn.com/logos/react.svg"
+  src="https://cdn.svglogos.dev/logos/react.svg"
   title="React"
   uniqueHash="a1f8d1"
   uniquifyIDs={true}
@@ -144,7 +136,7 @@ Create unique IDs for each icon.
 You can use the browser's cache to store the SVGs permanently.  
 To set it up, wrap your app with the cache provider:
 
-```typescript
+```tsx
 import { createRoot } from 'react-dom/client';
 import CacheProvider from 'react-inlinesvg/provider';
 import App from './App';
@@ -156,21 +148,23 @@ createRoot(document.getElementById('root')!).render(
 );
 ```
 
+The `CacheProvider` accepts an optional `name` prop to customize the cache storage name.
+
 > Be aware of the limitations of the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
 
 ## Browser Support
 
-Any browsers that support inlining [SVGs](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg) and [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) will work.
+Any browser that supports inlining [SVGs](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg) and [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) will work.
 
-If you need to support legacy browsers, include a polyfill for `fetch` and `Number.isNaN` in your app.
+If you need to support legacy browsers, include a polyfill for `fetch` in your app.
 
 ## CORS
 
-If you are loading remote SVGs, you must ensure it has [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support.
+If you are loading remote SVGs, you must ensure they have [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) headers.
 
 ## Why do you need this package?
 
-One of the reasons SVGs are awesome is that you can style them with CSS.
+One reason SVGs are awesome is that you can style them with CSS.
 Unfortunately, this is not useful in practice because the style element has to be in the same document. This leaves you with three bad options:
 
 1. Embed the CSS in the SVG document
@@ -192,7 +186,7 @@ But there's an alternative that sidesteps these issues: load the SVG with a GET
 
 ### Note
 
-The SVG [`<use>`](http://css-tricks.com/svg-use-external-source) element can be used to achieve something similar to this component. See [this article](http://taye.me/blog/svg/a-guide-to-svg-use-elements) for more information and [this table](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use#Browser_compatibility) for browser support and caveats.
+The SVG [`<use>`](https://css-tricks.com/svg-use-external-source/) element can be used to achieve something similar to this component. See [this article](https://taye.me/blog/svg/a-guide-to-svg-use-elements) for more information and [this table](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/use#Browser_compatibility) for browser support and caveats.
 
 ## Credits
 

package/dist/cache-NLB60kAd.d.mts

@@ -0,0 +1,142 @@
+import { SVGProps, ReactNode, Ref } from 'react';
+
+declare const STATUS: {
+    readonly IDLE: "idle";
+    readonly LOADING: "loading";
+    readonly LOADED: "loaded";
+    readonly FAILED: "failed";
+    readonly READY: "ready";
+    readonly UNSUPPORTED: "unsupported";
+};
+
+/**
+ * Called when loading the SVG fails.
+ */
+type ErrorCallback = (error: Error | FetchError) => void;
+/**
+ * Called when the SVG loads successfully.
+ */
+type LoadCallback = (src: string, isCached: boolean) => void;
+/**
+ * Pre-processes the SVG string before parsing.
+ * Must return a string.
+ */
+type PreProcessorCallback = (code: string) => string;
+type Props = Simplify<Omit<SVGProps<SVGElement>, 'onLoad' | 'onError' | 'ref'> & {
+    /**
+     * A URL to prepend to url() references inside the SVG when using `uniquifyIDs`.
+     * Only required if your page uses an HTML `<base>` tag.
+     */
+    baseURL?: string;
+    /**
+     * Cache remote SVGs in memory.
+     *
+     * When used with the CacheProvider, requests are also persisted in the browser cache.
+     * @default true
+     */
+    cacheRequests?: boolean;
+    /**
+     * Fallback content rendered on fetch error or unsupported browser.
+     */
+    children?: ReactNode;
+    /**
+     * A description for the SVG.
+     * Overrides an existing `<desc>` tag.
+     */
+    description?: string;
+    /**
+     * Custom options for the fetch request.
+     */
+    fetchOptions?: RequestInit;
+    /**
+     * A ref to the rendered SVG element.
+     * Not available on initial render — use `onLoad` instead.
+     */
+    innerRef?: Ref<SVGElement | null>;
+    /**
+     * A component shown while the SVG is loading.
+     */
+    loader?: ReactNode;
+    /**
+     * Called when loading the SVG fails.
+     * Receives an `Error` or `FetchError`.
+     */
+    onError?: ErrorCallback;
+    /**
+     * Called when the SVG loads successfully.
+     * Receives the `src` and an `isCached` flag.
+     */
+    onLoad?: LoadCallback;
+    /**
+     * A function to pre-process the SVG string before parsing.
+     * Must return a string.
+     */
+    preProcessor?: PreProcessorCallback;
+    /**
+     * The SVG to load.
+     * Accepts a URL or path, a data URI (base64 or URL-encoded), or a raw SVG string.
+     */
+    src: string;
+    /**
+     * A title for the SVG. Overrides an existing `<title>` tag.
+     * Pass `null` to remove it.
+     */
+    title?: string | null;
+    /**
+     * A string to use with `uniquifyIDs`.
+     * @default random 8-character alphanumeric string
+     */
+    uniqueHash?: string;
+    /**
+     * Create unique IDs for each icon.
+     * @default false
+     */
+    uniquifyIDs?: boolean;
+}>;
+type Simplify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+} & {};
+type Status = (typeof STATUS)[keyof typeof STATUS];
+interface FetchError extends Error {
+    code: string;
+    errno: string;
+    message: string;
+    type: string;
+}
+interface State {
+    content: string;
+    element: ReactNode;
+    isCached: boolean;
+    status: Status;
+}
+interface StorageItem {
+    content: string;
+    status: Status;
+}
+
+interface CacheStoreOptions {
+    name?: string;
+    persistent?: boolean;
+}
+declare class CacheStore {
+    private cacheApi;
+    private readonly cacheStore;
+    private readonly subscribers;
+    isReady: boolean;
+    constructor(options?: CacheStoreOptions);
+    onReady(callback: () => void): () => void;
+    private waitForReady;
+    get(url: string, fetchOptions?: RequestInit): Promise<string>;
+    getContent(url: string): string;
+    set(url: string, data: StorageItem): void;
+    isCached(url: string): boolean;
+    private fetchAndCache;
+    private fetchFromPersistentCache;
+    private handleLoading;
+    keys(): Array<string>;
+    data(): Array<Record<string, StorageItem>>;
+    delete(url: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+export { CacheStore as C, type ErrorCallback as E, type FetchError as F, type LoadCallback as L, type Props as P, type Simplify as S, type PreProcessorCallback as a, type State as b, type Status as c, type StorageItem as d };

package/dist/cache-NLB60kAd.d.ts

@@ -0,0 +1,142 @@
+import { SVGProps, ReactNode, Ref } from 'react';
+
+declare const STATUS: {
+    readonly IDLE: "idle";
+    readonly LOADING: "loading";
+    readonly LOADED: "loaded";
+    readonly FAILED: "failed";
+    readonly READY: "ready";
+    readonly UNSUPPORTED: "unsupported";
+};
+
+/**
+ * Called when loading the SVG fails.
+ */
+type ErrorCallback = (error: Error | FetchError) => void;
+/**
+ * Called when the SVG loads successfully.
+ */
+type LoadCallback = (src: string, isCached: boolean) => void;
+/**
+ * Pre-processes the SVG string before parsing.
+ * Must return a string.
+ */
+type PreProcessorCallback = (code: string) => string;
+type Props = Simplify<Omit<SVGProps<SVGElement>, 'onLoad' | 'onError' | 'ref'> & {
+    /**
+     * A URL to prepend to url() references inside the SVG when using `uniquifyIDs`.
+     * Only required if your page uses an HTML `<base>` tag.
+     */
+    baseURL?: string;
+    /**
+     * Cache remote SVGs in memory.
+     *
+     * When used with the CacheProvider, requests are also persisted in the browser cache.
+     * @default true
+     */
+    cacheRequests?: boolean;
+    /**
+     * Fallback content rendered on fetch error or unsupported browser.
+     */
+    children?: ReactNode;
+    /**
+     * A description for the SVG.
+     * Overrides an existing `<desc>` tag.
+     */
+    description?: string;
+    /**
+     * Custom options for the fetch request.
+     */
+    fetchOptions?: RequestInit;
+    /**
+     * A ref to the rendered SVG element.
+     * Not available on initial render — use `onLoad` instead.
+     */
+    innerRef?: Ref<SVGElement | null>;
+    /**
+     * A component shown while the SVG is loading.
+     */
+    loader?: ReactNode;
+    /**
+     * Called when loading the SVG fails.
+     * Receives an `Error` or `FetchError`.
+     */
+    onError?: ErrorCallback;
+    /**
+     * Called when the SVG loads successfully.
+     * Receives the `src` and an `isCached` flag.
+     */
+    onLoad?: LoadCallback;
+    /**
+     * A function to pre-process the SVG string before parsing.
+     * Must return a string.
+     */
+    preProcessor?: PreProcessorCallback;
+    /**
+     * The SVG to load.
+     * Accepts a URL or path, a data URI (base64 or URL-encoded), or a raw SVG string.
+     */
+    src: string;
+    /**
+     * A title for the SVG. Overrides an existing `<title>` tag.
+     * Pass `null` to remove it.
+     */
+    title?: string | null;
+    /**
+     * A string to use with `uniquifyIDs`.
+     * @default random 8-character alphanumeric string
+     */
+    uniqueHash?: string;
+    /**
+     * Create unique IDs for each icon.
+     * @default false
+     */
+    uniquifyIDs?: boolean;
+}>;
+type Simplify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+} & {};
+type Status = (typeof STATUS)[keyof typeof STATUS];
+interface FetchError extends Error {
+    code: string;
+    errno: string;
+    message: string;
+    type: string;
+}
+interface State {
+    content: string;
+    element: ReactNode;
+    isCached: boolean;
+    status: Status;
+}
+interface StorageItem {
+    content: string;
+    status: Status;
+}
+
+interface CacheStoreOptions {
+    name?: string;
+    persistent?: boolean;
+}
+declare class CacheStore {
+    private cacheApi;
+    private readonly cacheStore;
+    private readonly subscribers;
+    isReady: boolean;
+    constructor(options?: CacheStoreOptions);
+    onReady(callback: () => void): () => void;
+    private waitForReady;
+    get(url: string, fetchOptions?: RequestInit): Promise<string>;
+    getContent(url: string): string;
+    set(url: string, data: StorageItem): void;
+    isCached(url: string): boolean;
+    private fetchAndCache;
+    private fetchFromPersistentCache;
+    private handleLoading;
+    keys(): Array<string>;
+    data(): Array<Record<string, StorageItem>>;
+    delete(url: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+export { CacheStore as C, type ErrorCallback as E, type FetchError as F, type LoadCallback as L, type Props as P, type Simplify as S, type PreProcessorCallback as a, type State as b, type Status as c, type StorageItem as d };

package/dist/index.d.mts

@@ -1,75 +1,9 @@
-import React, { SVGProps, ReactNode, Ref } from 'react';
+import * as react from 'react';
+import { ReactElement } from 'react';
+import { C as CacheStore, P as Props } from './cache-NLB60kAd.mjs';
+export { E as ErrorCallback, F as FetchError, L as LoadCallback, a as PreProcessorCallback, S as Simplify, b as State, c as Status, d as StorageItem } from './cache-NLB60kAd.mjs';
 
-declare const STATUS: {
-    readonly IDLE: "idle";
-    readonly LOADING: "loading";
-    readonly LOADED: "loaded";
-    readonly FAILED: "failed";
-    readonly READY: "ready";
-    readonly UNSUPPORTED: "unsupported";
-};
+declare const cacheStore: CacheStore;
+declare function InlineSVG(props: Props): string | number | bigint | boolean | ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | null;
 
-type ErrorCallback = (error: Error | FetchError) => void;
-type LoadCallback = (src: string, isCached: boolean) => void;
-type PlainObject<T = unknown> = Record<string, T>;
-type PreProcessorCallback = (code: string) => string;
-type Props = Simplify<Omit<SVGProps<SVGElement>, 'onLoad' | 'onError' | 'ref'> & {
-    baseURL?: string;
-    cacheRequests?: boolean;
-    children?: ReactNode;
-    description?: string;
-    fetchOptions?: RequestInit;
-    innerRef?: Ref<SVGElement | null>;
-    loader?: ReactNode;
-    onError?: ErrorCallback;
-    onLoad?: LoadCallback;
-    preProcessor?: PreProcessorCallback;
-    src: string;
-    title?: string | null;
-    uniqueHash?: string;
-    uniquifyIDs?: boolean;
-}>;
-type Simplify<T> = {
-    [KeyType in keyof T]: T[KeyType];
-} & {};
-type Status = (typeof STATUS)[keyof typeof STATUS];
-interface FetchError extends Error {
-    code: string;
-    errno: string;
-    message: string;
-    type: string;
-}
-interface State {
-    content: string;
-    element: ReactNode;
-    isCached: boolean;
-    status: Status;
-}
-interface StorageItem {
-    content: string;
-    status: Status;
-}
-
-declare class CacheStore {
-    private cacheApi;
-    private readonly cacheStore;
-    private readonly subscribers;
-    isReady: boolean;
-    constructor();
-    onReady(callback: () => void): void;
-    get(url: string, fetchOptions?: RequestInit): Promise<string>;
-    set(url: string, data: StorageItem): void;
-    isCached(url: string): boolean;
-    private fetchAndAddToInternalCache;
-    private fetchAndAddToPersistentCache;
-    private handleLoading;
-    keys(): Array<string>;
-    data(): Array<Record<string, StorageItem>>;
-    delete(url: string): Promise<void>;
-    clear(): Promise<void>;
-}
-
-declare let cacheStore: CacheStore;
-declare function InlineSVG(props: Props): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
-
-export { type ErrorCallback, type FetchError, type LoadCallback, type PlainObject, type PreProcessorCallback, type Props, type Simplify, type State, type Status, type StorageItem, cacheStore, InlineSVG as default };
+export { Props, cacheStore, InlineSVG as default };

package/dist/index.d.ts

@@ -1,76 +1,10 @@
-import React, { SVGProps, ReactNode, Ref } from 'react';
+import * as react from 'react';
+import { ReactElement } from 'react';
+import { C as CacheStore, P as Props } from './cache-NLB60kAd.js';
+export { E as ErrorCallback, F as FetchError, L as LoadCallback, a as PreProcessorCallback, S as Simplify, b as State, c as Status, d as StorageItem } from './cache-NLB60kAd.js';
 
-declare const STATUS: {
-    readonly IDLE: "idle";
-    readonly LOADING: "loading";
-    readonly LOADED: "loaded";
-    readonly FAILED: "failed";
-    readonly READY: "ready";
-    readonly UNSUPPORTED: "unsupported";
-};
+declare const cacheStore: CacheStore;
+declare function InlineSVG(props: Props): string | number | bigint | boolean | ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | null;
 
-type ErrorCallback = (error: Error | FetchError) => void;
-type LoadCallback = (src: string, isCached: boolean) => void;
-type PlainObject<T = unknown> = Record<string, T>;
-type PreProcessorCallback = (code: string) => string;
-type Props = Simplify<Omit<SVGProps<SVGElement>, 'onLoad' | 'onError' | 'ref'> & {
-    baseURL?: string;
-    cacheRequests?: boolean;
-    children?: ReactNode;
-    description?: string;
-    fetchOptions?: RequestInit;
-    innerRef?: Ref<SVGElement | null>;
-    loader?: ReactNode;
-    onError?: ErrorCallback;
-    onLoad?: LoadCallback;
-    preProcessor?: PreProcessorCallback;
-    src: string;
-    title?: string | null;
-    uniqueHash?: string;
-    uniquifyIDs?: boolean;
-}>;
-type Simplify<T> = {
-    [KeyType in keyof T]: T[KeyType];
-} & {};
-type Status = (typeof STATUS)[keyof typeof STATUS];
-interface FetchError extends Error {
-    code: string;
-    errno: string;
-    message: string;
-    type: string;
-}
-interface State {
-    content: string;
-    element: ReactNode;
-    isCached: boolean;
-    status: Status;
-}
-interface StorageItem {
-    content: string;
-    status: Status;
-}
-
-declare class CacheStore {
-    private cacheApi;
-    private readonly cacheStore;
-    private readonly subscribers;
-    isReady: boolean;
-    constructor();
-    onReady(callback: () => void): void;
-    get(url: string, fetchOptions?: RequestInit): Promise<string>;
-    set(url: string, data: StorageItem): void;
-    isCached(url: string): boolean;
-    private fetchAndAddToInternalCache;
-    private fetchAndAddToPersistentCache;
-    private handleLoading;
-    keys(): Array<string>;
-    data(): Array<Record<string, StorageItem>>;
-    delete(url: string): Promise<void>;
-    clear(): Promise<void>;
-}
-
-declare let cacheStore: CacheStore;
-declare function InlineSVG(props: Props): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
-
-export { type ErrorCallback, type FetchError, type LoadCallback, type PlainObject, type PreProcessorCallback, type Props, type Simplify, type State, type Status, type StorageItem, cacheStore, InlineSVG as default };
+export { Props, cacheStore, InlineSVG as default };
 export = InlineSVG