react-inlinesvg 3.0.2 → 3.1.0-0

package/README.md

@@ -1,8 +1,8 @@
 # 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) [![Maintainability](https://api.codeclimate.com/v1/badges/c7e42fe511b80cc25760/maintainability)](https://codeclimate.com/github/gilbarbara/react-inlinesvg/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/c7e42fe511b80cc25760/test_coverage)](https://codeclimate.com/github/gilbarbara/react-inlinesvg/test_coverage)
+[![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)
 
-Load inline, local or remote SVGs in your React components.
+Load inline, local, or remote SVGs in your React components.
 
 View the [demo](https://codesandbox.io/s/github/gilbarbara/react-inlinesvg/tree/main/demo)
 
@@ -43,11 +43,11 @@ 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._
+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._
 
 **baseURL** {string}  
-An URL to prefix each ID in case you are using the `<base>` tag and `uniquifyIDs`.
+An URL to prefix each ID in case you use the `<base>` tag and `uniquifyIDs`.
 
 **children** {ReactNode}  
 The fallback content in case of a fetch error or unsupported browser.
@@ -100,13 +100,14 @@ This will receive a single argument with:
 
 **onLoad** {function}.  
 A callback to be invoked upon successful load.  
-This will receive 2 arguments: the `src` prop and a `hasCache` boolean
+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.
 
-**title** {string}  
-A title for your SVG. It will override an existing `<title>` tag.
+**title** {string | null}  
+A title for your SVG. It will override an existing `<title>` tag.  
+If `null` is passed, the `<title>` tag will be removed.
 
 **uniqueHash** {string} ▶︎ a random 8 characters string `[A-Za-z0-9]`  
 A string to use with `uniquifyIDs`.
@@ -125,7 +126,7 @@ Create unique IDs for each icon.
   description="The React logo"
   loader={<span>Loading...</span>}
   onError={(error) => console.log(error.message)}
-  onLoad={(src, hasCache) => console.log(src, hasCache)}
+  onLoad={(src, isCached) => console.log(src, isCached)}
   preProcessor={(code) => code.replace(/fill=".*?"/g, 'fill="currentColor"')}
   src="https://cdn.svgporn.com/logos/react.svg"
   title="React"
@@ -137,8 +138,26 @@ Create unique IDs for each icon.
 ## Caching
 
 The internal cache is exported as `cacheStore` if you need to debug or pre-cache some files.  
+Since version 4.x, the `cacheStore` is an instance of the [Cache](src/cache.ts) class instead of a plain object.  
 ⚠️ Use it at your own risk.
 
+### Persistent cache
+
+Starting with version 4.x you can use browser's [cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) to store the SVGs persistently.  
+To set it up, you need to wrap your app with the provider:
+
+```typescript
+import { createRoot } from 'react-dom/client';
+import CacheProvider from 'react-inlinesvg/provider';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <CacheProvider>
+    <App />
+  </CacheProvider>
+);
+```
+
 ## 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.
@@ -147,12 +166,12 @@ If you need to support legacy browsers you'll need to include a polyfiil for `fe
 
 ## CORS
 
-If you are loading remote SVGs, you'll need to make sure it has [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support.
+If you are loading remote SVGs, you'll need to ensure it has [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) support.
 
-## Why you need this package?
+## Why do you need this package?
 
-One of the reasons SVGs are awesome is because you can style them with CSS.
-Unfortunately, this winds up not being too useful in practice because the style element has to be in the same document. This leaves you with three bad options:
+One of the reasons 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
    - Can't use your CSS preprocessors (LESS, SASS)

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+
+declare const STATUS: {
+    readonly IDLE: "idle";
+    readonly LOADING: "loading";
+    readonly LOADED: "loaded";
+    readonly FAILED: "failed";
+    readonly READY: "ready";
+    readonly UNSUPPORTED: "unsupported";
+};
+
+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;
+interface Props extends Omit<React.SVGProps<SVGElement>, 'onLoad' | 'onError' | 'ref'> {
+    baseURL?: string;
+    cacheRequests?: boolean;
+    children?: React.ReactNode;
+    description?: string;
+    fetchOptions?: RequestInit;
+    innerRef?: React.Ref<SVGElement>;
+    loader?: React.ReactNode;
+    onError?: ErrorCallback;
+    onLoad?: LoadCallback;
+    preProcessor?: PreProcessorCallback;
+    src: string;
+    title?: string | null;
+    uniqueHash?: string;
+    uniquifyIDs?: boolean;
+}
+interface State {
+    content: string;
+    element: React.ReactNode;
+    isCached: boolean;
+    status: Status;
+}
+interface FetchError extends Error {
+    code: string;
+    errno: string;
+    message: string;
+    type: string;
+}
+type Status = (typeof STATUS)[keyof typeof STATUS];
+interface StorageItem {
+    content: string;
+    status: Status;
+}
+
+declare class CacheStore {
+    private cacheApi;
+    private readonly cacheStore;
+    private readonly subscribers;
+    private readonly usePersistentCache;
+    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_runtime.JSX.Element | null;
+
+export { ErrorCallback, FetchError, LoadCallback, PlainObject, PreProcessorCallback, Props, State, Status, StorageItem, cacheStore, InlineSVG as default };

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+
+declare const STATUS: {
+    readonly IDLE: "idle";
+    readonly LOADING: "loading";
+    readonly LOADED: "loaded";
+    readonly FAILED: "failed";
+    readonly READY: "ready";
+    readonly UNSUPPORTED: "unsupported";
+};
+
+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;
+interface Props extends Omit<React.SVGProps<SVGElement>, 'onLoad' | 'onError' | 'ref'> {
+    baseURL?: string;
+    cacheRequests?: boolean;
+    children?: React.ReactNode;
+    description?: string;
+    fetchOptions?: RequestInit;
+    innerRef?: React.Ref<SVGElement>;
+    loader?: React.ReactNode;
+    onError?: ErrorCallback;
+    onLoad?: LoadCallback;
+    preProcessor?: PreProcessorCallback;
+    src: string;
+    title?: string | null;
+    uniqueHash?: string;
+    uniquifyIDs?: boolean;
+}
+interface State {
+    content: string;
+    element: React.ReactNode;
+    isCached: boolean;
+    status: Status;
+}
+interface FetchError extends Error {
+    code: string;
+    errno: string;
+    message: string;
+    type: string;
+}
+type Status = (typeof STATUS)[keyof typeof STATUS];
+interface StorageItem {
+    content: string;
+    status: Status;
+}
+
+declare class CacheStore {
+    private cacheApi;
+    private readonly cacheStore;
+    private readonly subscribers;
+    private readonly usePersistentCache;
+    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_runtime.JSX.Element | null;
+
+export { ErrorCallback, FetchError, LoadCallback, PlainObject, PreProcessorCallback, Props, State, Status, StorageItem, cacheStore, InlineSVG as default };