@rokku-x/react-hook-loading-spinner 0.1.0

package/README.md

@@ -0,0 +1,639 @@
+# react-hook-loading-spinner
+
+A lightweight and flexible React loading state hook library with built-in spinner components, global state management, and zero dependencies (except React and Zustand).
+
+## Installation
+
+```bash
+npm install @rokku-x/react-hook-loading-spinner
+```
+
+## Features
+
+- 🎯 **Global Loading State** - Centralized loading management across your entire app
+- 🪝 **React Hooks API** - Easy-to-use hook-based interface with automatic cleanup
+- 🔄 **Reference Counting** - Multiple components can start/stop loading independently
+- ⚡ **Async/Await Support** - Built-in async wrapper for promises
+- 🎨 **Customizable Spinners** - Pre-built components or bring your own
+- 📦 **TypeScript Support** - Full type safety out of the box
+- 🎭 **Multiple Animations** - Spin, fade, or no animation
+- 📡 **Event System** - Subscribe to loading state changes
+- ♿ **Accessibility** - Built-in inert attribute and scroll prevention
+- 📱 **Zero Dependencies** - Only requires React and Zustand
+
+## Bundle Size
+
+- ESM: 4.23 kB gzipped (12.80 kB raw)
+- CJS: 3.67 kB gzipped (9.31 kB raw)
+
+## Runtime Performance
+
+- **startLoading()**: 0.025ms per operation
+- **stopLoading()**: 0.0006ms per operation
+- **start/stop cycle**: 0.023ms per cycle
+- **asyncUseLoading()**: 0.076ms per operation (overhead)
+- **overrideLoading()**: 0.011ms per operation
+- **10 instances start/stop**: 0.269ms per cycle
+
+All measurements are extremely fast, with even 1000 operations completing in milliseconds. Measurements based on actual benchmarks in test suite.
+
+## Quick Start
+
+### 1. Setup the Loading Renderer
+
+First, add the `LoadingRenderer` at the root of your application:
+
+```tsx
+import { LoadingRenderer } from '@rokku-x/react-hook-loading-spinner';
+
+function App() {
+  return (
+    <>
+      <YourComponents />
+      <LoadingRenderer />
+    </>
+  );
+}
+```
+
+### 2. Use the Loading Hook
+
+```tsx
+import { useLoading } from '@rokku-x/react-hook-loading-spinner';
+
+function MyComponent() {
+  const { startLoading, stopLoading, isLoading } = useLoading();
+  
+  const handleClick = async () => {
+    startLoading();
+    try {
+      await fetchData();
+    } finally {
+      stopLoading();
+    }
+  };
+  
+  return (
+    <button onClick={handleClick} disabled={isLoading}>
+      {isLoading ? 'Loading...' : 'Fetch Data'}
+    </button>
+  );
+}
+```
+
+## API Reference
+
+### LoadingRenderer
+
+The main component that renders the loading spinner overlay. Must be mounted at the root level.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `loadingComponent` | `React.ComponentType \| React.ReactElement` | `LoadingCircle` | Custom loading component to display |
+| `loadingComponentScale` | `number` | `1` | Scale factor for the loading component |
+| `animationType` | `AnimationType` | `AnimationType.Spin` | Animation type: `'spin'`, `'fadeInOut'`, or `'none'` |
+| `animationDuration` | `number` | `1` (spin) or `2` (fade) | Animation duration in seconds |
+| `wrapperStyle` | `CSSProperties` | `undefined` | Inline styles for the dialog wrapper |
+| `wrapperClassName` | `string` | `undefined` | CSS class for the dialog wrapper |
+| `wrapperId` | `string` | `'loading-wrapper-{random}'` | Unique identifier for the wrapper |
+| `animationWrapperStyle` | `CSSProperties` | `undefined` | Inline styles for the animation wrapper |
+| `animationWrapperClassName` | `string` | `undefined` | CSS class for the animation wrapper |
+| `animationWrapperId` | `string` | `undefined` | ID for the animation wrapper |
+
+#### Built-in Loading Components
+
+| Component | Description |
+|-----------|-------------|
+| `LoadingCircle` | Spinning circle spinner (default) |
+| `LoadingPleaseWait` | "Please wait..." text |
+
+### useLoading
+
+Hook for managing loading state in your components.
+
+#### Returns
+
+```typescript
+{
+  startLoading: () => void,
+  stopLoading: () => void,
+  asyncUseLoading: <R>(promise: Promise<R>) => Promise<R>,
+  overrideLoading: (state: boolean | null) => void,
+  isLoading: boolean,
+  isLocalLoading: boolean
+}
+```
+
+| Return Value | Type | Description |
+|---|---|---|
+| `startLoading` | `() => void` | Increment the loading counter (starts loading) |
+| `stopLoading` | `() => void` | Decrement the loading counter (stops loading when reaches 0) |
+| `asyncUseLoading` | `<R>(promise: Promise<R>) => Promise<R>` | Wrap a promise to automatically manage loading state |
+| `overrideLoading` | `(state: boolean \| null) => void` | Override the loading state (null = remove override) |
+| `isLoading` | `boolean` | Global loading state (true if any component is loading) |
+| `isLocalLoading` | `boolean` | Local loading state for this hook instance only |
+
+### Loading Component
+
+A component that triggers loading state based on a prop.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isLoading` | `boolean` | `false` | Whether to show loading state |
+
+#### Example
+
+```tsx
+import { Loading } from 'react-hook-loading-spinner';
+
+function MyComponent() {
+  const [fetching, setFetching] = useState(false);
+  
+  return (
+    <>
+      <Loading isLoading={fetching} />
+      {/* Your component */}
+    </>
+  );
+}
+```
+
+### AnimationType
+
+```typescript
+const AnimationType = {
+  Spin: 'spin',
+  FadeInOut: 'fadeInOut',
+  None: 'none',
+} as const;
+```
+
+### loadingEventTarget
+
+Event emitter for subscribing to loading state changes.
+
+#### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `'change'` | `{ isLoading: boolean, isOverrideState: boolean }` | Emitted whenever loading state changes |
+| `'start'` | `null` | Emitted when loading starts (transitions from false to true) |
+| `'stop'` | `null` | Emitted when loading stops (transitions from true to false) |
+
+#### Example
+
+```tsx
+import { loadingEventTarget } from 'react-hook-loading-spinner';
+
+useEffect(() => {
+  const listener = loadingEventTarget.on('change', ({ isLoading }) => {
+    console.log('Loading state changed:', isLoading);
+  });
+  
+  return () => listener.removeAllListeners();
+}, []);
+```
+
+## Examples
+
+### Example 1: Basic Loading
+
+```tsx
+import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';
+
+function App() {
+  return (
+    <>
+      <BasicLoadingExample />
+      <LoadingRenderer />
+    </>
+  );
+}
+
+function BasicLoadingExample() {
+  const { startLoading, stopLoading } = useLoading();
+  
+  const handleFetch = async () => {
+    startLoading();
+    try {
+      await fetch('https://api.example.com/data');
+    } finally {
+      stopLoading();
+    }
+  };
+  
+  return <button onClick={handleFetch}>Fetch Data</button>;
+}
+```
+
+### Example 2: Async Wrapper
+
+The `asyncUseLoading` method automatically manages loading state for promises.
+
+```tsx
+import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';
+
+function AsyncExample() {
+  const { asyncUseLoading } = useLoading();
+  
+  const handleFetch = async () => {
+    // Loading state is automatically managed
+    const data = await asyncUseLoading(
+      fetch('https://api.example.com/data').then(res => res.json())
+    );
+    console.log(data);
+  };
+  
+  return <button onClick={handleFetch}>Fetch Data</button>;
+}
+
+function App() {
+  return (
+    <>
+      <AsyncExample />
+      <LoadingRenderer />
+    </>
+  );
+}
+```
+
+### Example 3: Multiple Loading States
+
+Multiple components can start loading independently. The loading indicator stays visible until all have stopped.
+
+```tsx
+import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';
+
+function MultipleLoadingExample() {
+  const { asyncUseLoading } = useLoading();
+  
+  const fetchUser = () => asyncUseLoading(
+    fetch('https://api.example.com/user').then(res => res.json())
+  );
+  
+  const fetchPosts = () => asyncUseLoading(
+    fetch('https://api.example.com/posts').then(res => res.json())
+  );
+  
+  const fetchAll = async () => {
+    // Both requests will show loading
+    // Loading stops when both complete
+    await Promise.all([fetchUser(), fetchPosts()]);
+  };
+  
+  return (
+    <div>
+      <button onClick={fetchUser}>Fetch User</button>
+      <button onClick={fetchPosts}>Fetch Posts</button>
+      <button onClick={fetchAll}>Fetch All</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <>
+      <MultipleLoadingExample />
+      <LoadingRenderer />
+    </>
+  );
+}
+```
+
+### Example 4: Local Loading State
+
+Track loading state for individual components without affecting global state visibility.
+
+```tsx
+import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';
+
+function LocalLoadingExample() {
+  const { startLoading, stopLoading, isLocalLoading } = useLoading();
+  
+  const handleClick = async () => {
+    startLoading();
+    try {
+      await fetch('https://api.example.com/data');
+    } finally {
+      stopLoading();
+    }
+  };
+  
+  return (
+    <button onClick={handleClick} disabled={isLocalLoading}>
+      {isLocalLoading ? 'Loading...' : 'Fetch Data'}
+    </button>
+  );
+}
+
+function App() {
+  return (
+    <>
+      <LocalLoadingExample />
+      <LoadingRenderer />
+    </>
+  );
+}
+```
+
+### Example 5: Override Loading State
+
+Force loading state on or off, bypassing the reference counting.
+
+```tsx
+import { useLoading, LoadingRenderer } from 'react-hook-loading-spinner';
+
+function OverrideExample() {
+  const { overrideLoading, isLoading } = useLoading();
+  
+  const forceLoading = () => overrideLoading(true);
+  const clearOverride = () => overrideLoading(null);
+  
+  return (
+    <div>
+      <button onClick={forceLoading}>Force Loading</button>
+      <button onClick={clearOverride}>Clear Override</button>
+      <p>Loading: {isLoading ? 'Yes' : 'No'}</p>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <>
+      <OverrideExample />
+      <LoadingRenderer />
+    </>
+  );
+}
+```
+
+### Example 6: Custom Loading Component
+
+```tsx
+import { LoadingRenderer } from 'react-hook-loading-spinner';
+
+const CustomSpinner = () => (
+  <div style={{
+    width: '100px',
+    height: '100px',
+    border: '10px solid #e0e0e0',
+    borderTop: '10px solid #3498db',
+    borderRadius: '50%',
+  }} />
+);
+
+function App() {
+  return (
+    <>
+      <YourComponents />
+      <LoadingRenderer 
+        loadingComponent={CustomSpinner}
+        loadingComponentScale={1.5}
+      />
+    </>
+  );
+}
+```
+
+### Example 7: Fade Animation
+
+```tsx
+import { LoadingRenderer, AnimationType, LoadingPleaseWait } from 'react-hook-loading-spinner';
+
+function App() {
+  return (
+    <>
+      <YourComponents />
+      <LoadingRenderer 
+        loadingComponent={LoadingPleaseWait}
+        animationType={AnimationType.FadeInOut}
+        animationDuration={1.5}
+      />
+    </>
+  );
+}
+```
+
+### Example 8: Custom Styling
+
+```tsx
+import { LoadingRenderer, LoadingCircle } from 'react-hook-loading-spinner';
+
+function App() {
+  return (
+    <>
+      <YourComponents />
+      <LoadingRenderer 
+        loadingComponent={LoadingCircle}
+        wrapperStyle={{
+          backgroundColor: 'rgba(0, 0, 0, 0.8)',
+          backdropFilter: 'blur(5px)',
+        }}
+        animationWrapperStyle={{
+          padding: '40px',
+          backgroundColor: 'white',
+          borderRadius: '16px',
+          boxShadow: '0 10px 40px rgba(0,0,0,0.3)',
+        }}
+      />
+    </>
+  );
+}
+```
+
+### Example 9: Loading Component Prop
+
+Use the `<Loading>` component to trigger loading based on a boolean prop.
+
+```tsx
+import { Loading, LoadingRenderer } from 'react-hook-loading-spinner';
+import { useState } from 'react';
+
+function LoadingComponentExample() {
+  const [isFetching, setIsFetching] = useState(false);
+  
+  const handleFetch = async () => {
+    setIsFetching(true);
+    try {
+      await fetch('https://api.example.com/data');
+    } finally {
+      setIsFetching(false);
+    }
+  };
+  
+  return (
+    <div>
+      <Loading isLoading={isFetching} />
+      <button onClick={handleFetch}>Fetch Data</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <>
+      <LoadingComponentExample />
+      <LoadingRenderer />
+    </>
+  );
+}
+```
+
+### Example 10: Event Listener
+
+Subscribe to loading state changes using the event system.
+
+```tsx
+import { loadingEventTarget, useLoading, LoadingRenderer } from 'react-hook-loading-spinner';
+import { useEffect, useState } from 'react';
+
+function EventListenerExample() {
+  const { startLoading, stopLoading } = useLoading();
+  const [loadingLog, setLoadingLog] = useState<string[]>([]);
+  
+  useEffect(() => {
+    const onChange = loadingEventTarget.on('change', ({ isLoading }) => {
+      setLoadingLog(prev => [...prev, `Changed: ${isLoading}`]);
+    });
+    
+    const onStart = loadingEventTarget.on('start', () => {
+      setLoadingLog(prev => [...prev, 'Started!']);
+    });
+    
+    const onStop = loadingEventTarget.on('stop', () => {
+      setLoadingLog(prev => [...prev, 'Stopped!']);
+    });
+    
+    return () => {
+      onChange.removeAllListeners();
+      onStart.removeAllListeners();
+      onStop.removeAllListeners();
+    };
+  }, []);
+  
+  return (
+    <div>
+      <button onClick={startLoading}>Start</button>
+      <button onClick={stopLoading}>Stop</button>
+      <ul>
+        {loadingLog.map((log, i) => <li key={i}>{log}</li>)}
+      </ul>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <>
+      <EventListenerExample />
+      <LoadingRenderer />
+    </>
+  );
+}
+```
+
+## How It Works
+
+### Reference Counting
+
+The library uses a reference counting system to manage loading state:
+
+1. Each call to `startLoading()` increments a counter
+2. Each call to `stopLoading()` decrements the counter
+3. Loading is active when the counter > 0
+4. Multiple components can independently manage loading
+
+### Local Tracking
+
+Each `useLoading()` hook instance maintains its own local counter:
+
+- `isLocalLoading` reflects only this instance's loading state
+- `startLoading()`/`stopLoading()` only affect the local counter
+- Local counter prevents calling `stopLoading()` more times than `startLoading()`
+
+### Global State
+
+The global loading state is managed by Zustand:
+
+- `isLoading` reflects whether ANY component is loading
+- Shared across all hook instances
+- Can be overridden with `overrideLoading()`
+
+## Best Practices
+
+1. **Always pair start/stop**: Use try/finally to ensure loading stops even on errors
+```tsx
+const { startLoading, stopLoading } = useLoading();
+
+const fetchData = async () => {
+  startLoading();
+  try {
+    await api.fetchData();
+  } finally {
+    stopLoading(); // Always called, even on error
+  }
+};
+```
+
+2. **Use async wrapper**: Let the library handle cleanup automatically
+```tsx
+const { asyncUseLoading } = useLoading();
+
+const fetchData = () => asyncUseLoading(api.fetchData());
+```
+
+3. **Disable buttons during loading**: Prevent duplicate requests
+```tsx
+const { isLocalLoading } = useLoading();
+
+<button disabled={isLocalLoading} onClick={fetchData}>
+  Fetch
+</button>
+```
+
+4. **Clean up event listeners**: Remove listeners in useEffect cleanup
+```tsx
+useEffect(() => {
+  const listener = loadingEventTarget.on('change', handleChange);
+  return () => listener.removeAllListeners();
+}, []);
+```
+
+## TypeScript
+
+The library is written in TypeScript and provides full type definitions.
+
+```typescript
+import { useLoading, AnimationType } from 'react-hook-loading-spinner';
+import type { AnimationTypeType } from 'react-hook-loading-spinner';
+
+const { startLoading, stopLoading, isLoading } = useLoading();
+
+const animation: AnimationTypeType = AnimationType.Spin;
+```
+
+## Browser Support
+
+- Modern browsers (Chrome, Firefox, Safari, Edge)
+- Requires support for:
+  - React 18+
+  - ES6+ features
+  - `<dialog>` element (with polyfill if needed)
+  - CSS animations
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Repository
+
+[https://github.com/rokku-x/react-hook-loading-spinner](https://github.com/rokku-x/react-hook-loading-spinner)

package/dist/components/Loading.d.ts

@@ -0,0 +1,3 @@
+export default function Loading({ isLoading }: {
+    isLoading: boolean;
+}): null;

package/dist/components/LoadingRenderer.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+export declare const AnimationType: {
+    readonly Spin: "spin";
+    readonly FadeInOut: "fadeInOut";
+    readonly None: "none";
+};
+export type AnimationType = (typeof AnimationType)[keyof typeof AnimationType];
+export declare const LoadingCircle: React.FC;
+export declare const LoadingPleaseWait: React.FC;
+export default function LoadingRenderer({ loadingComponent, loadingComponentScale, animationType, animationDuration, wrapperStyle, wrapperClassName, wrapperId, animationWrapperStyle, animationWrapperClassName, animationWrapperId }: {
+    loadingComponent?: React.ComponentType | React.ReactElement;
+    loadingComponentScale?: number;
+    animationType?: AnimationType;
+    animationDuration?: number;
+    wrapperStyle?: React.CSSProperties;
+    wrapperClassName?: string;
+    wrapperId?: string;
+    animationWrapperStyle?: React.CSSProperties;
+    animationWrapperClassName?: string;
+    animationWrapperId?: string;
+}): React.ReactPortal | null;

package/dist/hooks/useLoading.d.ts

@@ -0,0 +1,19 @@
+import { default as EventEmitter } from '../utils/EventEmitter';
+type LoadingEvents = {
+    change: {
+        isLoading: boolean;
+        isOverrideState: boolean;
+    } | null;
+    start: null;
+    stop: null;
+};
+export declare const loadingEventTarget: EventEmitter<LoadingEvents>;
+export default function useLoading(): {
+    overrideLoading: (state: boolean | null) => void;
+    startLoading: () => void;
+    stopLoading: () => void;
+    readonly isLocalLoading: boolean;
+    asyncUseLoading: <R, _ extends any[]>(asyncFunction: Promise<R>) => Promise<R>;
+    readonly isLoading: boolean;
+};
+export {};

package/dist/index.cjs.js

@@ -0,0 +1,30 @@
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const m=require("react"),h=require("react/jsx-runtime"),N=require("react-dom"),I=n=>{let t;const e=new Set,i=(f,r)=>{const d=typeof f=="function"?f(t):f;if(!Object.is(d,t)){const g=t;t=r??(typeof d!="object"||d===null)?d:Object.assign({},t,d),e.forEach(u=>u(t,g))}},o=()=>t,s={setState:i,getState:o,getInitialState:()=>p,subscribe:f=>(e.add(f),()=>e.delete(f))},p=t=n(i,o,s);return s},D=(n=>n?I(n):I),F=n=>n;function M(n,t=F){const e=m.useSyncExternalStore(n.subscribe,m.useCallback(()=>t(n.getState()),[n,t]),m.useCallback(()=>t(n.getInitialState()),[n,t]));return m.useDebugValue(e),e}const j=n=>{const t=D(n),e=i=>M(t,i);return Object.assign(e,t),e},P=(n=>n?j(n):j),T={BASE_URL:"/",DEV:!1,MODE:"production",PROD:!0,SSR:!1},C=new Map,x=n=>{const t=C.get(n);return t?Object.fromEntries(Object.entries(t.stores).map(([e,i])=>[e,i.getState()])):{}},$=(n,t,e)=>{if(n===void 0)return{type:"untracked",connection:t.connect(e)};const i=C.get(e.name);if(i)return{type:"tracked",store:n,...i};const o={connection:t.connect(e),stores:{}};return C.set(e.name,o),{type:"tracked",store:n,...o}},J=(n,t)=>{if(t===void 0)return;const e=C.get(n);e&&(delete e.stores[t],Object.keys(e.stores).length===0&&C.delete(n))},U=n=>{var t,e;if(!n)return;const i=n.split(`
+`),o=i.findIndex(v=>v.includes("api.setState"));if(o<0)return;const l=((t=i[o+1])==null?void 0:t.trim())||"";return(e=/.+ (.+) .+/.exec(l))==null?void 0:e[1]},z=(n,t={})=>(e,i,o)=>{const{enabled:l,anonymousActionType:v,store:s,...p}=t;let f;try{f=(l??(T?"production":void 0)!=="production")&&window.__REDUX_DEVTOOLS_EXTENSION__}catch{}if(!f)return n(e,i,o);const{connection:r,...d}=$(s,f,p);let g=!0;o.setState=((c,L,a)=>{const S=e(c,L);if(!g)return S;const O=a===void 0?{type:v||U(new Error().stack)||"anonymous"}:typeof a=="string"?{type:a}:a;return s===void 0?(r?.send(O,i()),S):(r?.send({...O,type:`${s}/${O.type}`},{...x(p.name),[s]:o.getState()}),S)}),o.devtools={cleanup:()=>{r&&typeof r.unsubscribe=="function"&&r.unsubscribe(),J(p.name,s)}};const u=(...c)=>{const L=g;g=!1,e(...c),g=L},E=n(o.setState,i,o);if(d.type==="untracked"?r?.init(E):(d.stores[d.store]=o,r?.init(Object.fromEntries(Object.entries(d.stores).map(([c,L])=>[c,c===d.store?E:L.getState()])))),o.dispatchFromDevtools&&typeof o.dispatch=="function"){let c=!1;const L=o.dispatch;o.dispatch=(...a)=>{(T?"production":void 0)!=="production"&&a[0].type==="__setState"&&!c&&(console.warn('[zustand devtools middleware] "__setState" action type is reserved to set state from the devtools. Avoid using it.'),c=!0),L(...a)}}return r.subscribe(c=>{var L;switch(c.type){case"ACTION":if(typeof c.payload!="string"){console.error("[zustand devtools middleware] Unsupported action format");return}return _(c.payload,a=>{if(a.type==="__setState"){if(s===void 0){u(a.state);return}Object.keys(a.state).length!==1&&console.error(`
+                    [zustand devtools middleware] Unsupported __setState action format.
+                    When using 'store' option in devtools(), the 'state' should have only one key, which is a value of 'store' that was passed in devtools(),
+                    and value of this only key should be a state object. Example: { "type": "__setState", "state": { "abc123Store": { "foo": "bar" } } }
+                    `);const S=a.state[s];if(S==null)return;JSON.stringify(o.getState())!==JSON.stringify(S)&&u(S);return}o.dispatchFromDevtools&&typeof o.dispatch=="function"&&o.dispatch(a)});case"DISPATCH":switch(c.payload.type){case"RESET":return u(E),s===void 0?r?.init(o.getState()):r?.init(x(p.name));case"COMMIT":if(s===void 0){r?.init(o.getState());return}return r?.init(x(p.name));case"ROLLBACK":return _(c.state,a=>{if(s===void 0){u(a),r?.init(o.getState());return}u(a[s]),r?.init(x(p.name))});case"JUMP_TO_STATE":case"JUMP_TO_ACTION":return _(c.state,a=>{if(s===void 0){u(a);return}JSON.stringify(o.getState())!==JSON.stringify(a[s])&&u(a[s])});case"IMPORT_STATE":{const{nextLiftedState:a}=c.payload,S=(L=a.computedStates.slice(-1)[0])==null?void 0:L.state;if(!S)return;u(s===void 0?S:S[s]),r?.send(null,a);return}case"PAUSE_RECORDING":return g=!g}return}}),E},W=z,_=(n,t)=>{let e;try{e=JSON.parse(n)}catch(i){console.error("[zustand devtools middleware] Could not parse the received json",i)}e!==void 0&&t(e)};class R extends EventTarget{constructor(){super(...arguments),this.controller=new AbortController}on(t,e){return this.addEventListener(t,i=>e(i.detail),{signal:this.controller.signal}),this}once(t,e){return this.addEventListener(t,i=>e(i.detail),{signal:this.controller.signal,once:!0}),this}emit(t,e){return this.dispatchEvent(new CustomEvent(t,{detail:e}))}removeAllListeners(){this.controller.abort(),this.controller=new AbortController}}const b=new R,V=P()(W((n,t)=>({loadingCount:0,overrideState:null,localCounters:{},isLoading(){return t().overrideState??t().loadingCount>0},actions:{isGlobalLoading(){return t().isLoading()},startLoading:e=>{const i=t().isLoading();n(l=>({loadingCount:l.loadingCount+1})),e&&n(l=>({localCounters:{...l.localCounters,[e]:(l.localCounters[e]??0)+1}}));const o=t().isLoading();o&&!i&&b.emit("start",null),b.emit("change",{isLoading:o,isOverrideState:t().overrideState!==null})},stopLoading:e=>{const i=t().isLoading(),o=e?t().localCounters[e]??0:0;e&&o>0&&n(v=>({loadingCount:Math.max(0,v.loadingCount-1),localCounters:{...v.localCounters,[e]:Math.max(0,v.localCounters[e]-1)}}));const l=t().isLoading();!l&&i&&b.emit("stop",null),b.emit("change",{isLoading:l,isOverrideState:t().overrideState!==null})},overrideLoading:e=>{const i=t().isLoading();n({overrideState:e});const o=t().isLoading();o&&!i?b.emit("start",null):!o&&i&&b.emit("stop",null),b.emit("change",{isLoading:o,isOverrideState:e!==null})},getLocalCounter:e=>t().localCounters[e]??0,isLocalLoading:e=>(t().localCounters[e]??0)>0}})));function w(){const n=m.useId(),{actions:t}=V(l=>l),e=()=>{t.startLoading(n)},i=()=>{t.isLocalLoading(n)&&t.stopLoading(n)},o=async l=>{e();try{return await l}finally{i()}};return{overrideLoading:t.overrideLoading,startLoading:e,stopLoading:i,get isLocalLoading(){return t.isLocalLoading(n)},asyncUseLoading:o,get isLoading(){return t.isGlobalLoading()}}}const y={Spin:"spin",FadeInOut:"fadeInOut",None:"none"},q=({scale:n=1,animationType:t=y.Spin,animationDuration:e,children:i,style:o,className:l,id:v,prefix:s})=>{const p=t,f=t===y.Spin?1:t===y.FadeInOut?2:0,r=e||f,d=t===y.Spin?"linear":t===y.FadeInOut?"ease-in-out":"linear",g=t===y.None?"none":`${s}-${p} ${r}s ${d} infinite`;return h.jsx("div",{style:{animation:g,...n!==1?{zoom:n}:{},...o},className:l,id:v,children:i})},A=n=>h.jsx("div",{id:"loading-circle",style:{width:"90px",height:"90px",border:"15px solid #f3f3f3",borderTop:"15px solid #009b4bff",borderRadius:"50%",boxSizing:"border-box"},...n}),k=n=>h.jsx("div",{style:{padding:"20px",fontSize:"25px",color:"#333",fontFamily:"system-ui, sans-serif"},...n,children:"Please wait..."});function B({loadingComponent:n,loadingComponentScale:t=1,animationType:e=y.Spin,animationDuration:i,wrapperStyle:o,wrapperClassName:l,wrapperId:v,animationWrapperStyle:s,animationWrapperClassName:p,animationWrapperId:f}){n=n||(e===y.Spin?A:k);const r=m.useRef(Math.random().toString(36).substring(2,6).replace(/[0-9]/g,"")),{isLoading:d}=w(),g=m.useRef(null);m.useEffect(()=>{d?(g.current?.showModal(),document.body.setAttribute("inert","")):(g.current?.close(),document.body.removeAttribute("inert"))},[d]);const u=v||"loading-wrapper-"+r.current;return d?N.createPortal(h.jsxs(h.Fragment,{children:[h.jsx("style",{children:`
+                        dialog#${u}[open] {
+                            display: flex !important;
+                            justify-content: center;
+                            align-items: center;
+                            width: 100vw;
+                            height: 100vh;
+                            max-width: 100%;
+                            max-height: 100%;
+                        }
+                        @keyframes ${r.current}-spin {
+                            0% { transform: rotate(0deg); }
+                            100% { transform: rotate(360deg); }
+                        }
+                        @keyframes ${r.current}-fadeInOut {
+                            0%, 100% { opacity: 0.2; }
+                            50% { opacity: 1; }
+                        }
+                        body:has(dialog#${u}[open]) {
+                            overflow: hidden;
+                        }
+                        body {
+                            scrollbar-gutter: stable;
+                        }
+                    `}),h.jsx("dialog",{ref:g,style:{border:"none",padding:0,backgroundColor:"rgba(0, 0, 0, 0.5)",backdropFilter:"blur(2px)",...o},className:l,id:u,children:h.jsx(q,{scale:t,animationType:e,animationDuration:i,style:s,className:p,id:f,prefix:r.current,children:m.isValidElement(n)?n:m.createElement(n)})})]}),document.body):null}function G({isLoading:n=!1}){const{startLoading:t,stopLoading:e}=w();return m.useEffect(()=>(n?t():e(),()=>{n&&e()}),[n]),null}exports.AnimationType=y;exports.EventEmitter=R;exports.Loading=G;exports.LoadingCircle=A;exports.LoadingPleaseWait=k;exports.LoadingRenderer=B;exports.loadingEventTarget=b;exports.useLoading=w;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { default as useLoading } from './hooks/useLoading';
+export { loadingEventTarget } from './hooks/useLoading';
+export { default as LoadingRenderer } from './components/LoadingRenderer';
+export { LoadingCircle, LoadingPleaseWait, AnimationType } from './components/LoadingRenderer';
+export type { AnimationType as AnimationTypeType } from './components/LoadingRenderer';
+export { default as Loading } from './components/Loading';
+export { default as EventEmitter } from './utils/EventEmitter';

package/dist/index.esm.js

@@ -0,0 +1,387 @@
+"use client";
+import y, { useId as N, useRef as x, useEffect as k } from "react";
+import { jsxs as j, Fragment as D, jsx as L } from "react/jsx-runtime";
+import { createPortal as F } from "react-dom";
+const I = (n) => {
+  let t;
+  const e = /* @__PURE__ */ new Set(), r = (f, i) => {
+    const d = typeof f == "function" ? f(t) : f;
+    if (!Object.is(d, t)) {
+      const g = t;
+      t = i ?? (typeof d != "object" || d === null) ? d : Object.assign({}, t, d), e.forEach((u) => u(t, g));
+    }
+  }, o = () => t, s = { setState: r, getState: o, getInitialState: () => p, subscribe: (f) => (e.add(f), () => e.delete(f)) }, p = t = n(r, o, s);
+  return s;
+}, M = ((n) => n ? I(n) : I), $ = (n) => n;
+function P(n, t = $) {
+  const e = y.useSyncExternalStore(
+    n.subscribe,
+    y.useCallback(() => t(n.getState()), [n, t]),
+    y.useCallback(() => t(n.getInitialState()), [n, t])
+  );
+  return y.useDebugValue(e), e;
+}
+const T = (n) => {
+  const t = M(n), e = (r) => P(t, r);
+  return Object.assign(e, t), e;
+}, J = ((n) => n ? T(n) : T), R = { BASE_URL: "/", DEV: !1, MODE: "production", PROD: !0, SSR: !1 }, C = /* @__PURE__ */ new Map(), w = (n) => {
+  const t = C.get(n);
+  return t ? Object.fromEntries(
+    Object.entries(t.stores).map(([e, r]) => [e, r.getState()])
+  ) : {};
+}, U = (n, t, e) => {
+  if (n === void 0)
+    return {
+      type: "untracked",
+      connection: t.connect(e)
+    };
+  const r = C.get(e.name);
+  if (r)
+    return { type: "tracked", store: n, ...r };
+  const o = {
+    connection: t.connect(e),
+    stores: {}
+  };
+  return C.set(e.name, o), { type: "tracked", store: n, ...o };
+}, z = (n, t) => {
+  if (t === void 0) return;
+  const e = C.get(n);
+  e && (delete e.stores[t], Object.keys(e.stores).length === 0 && C.delete(n));
+}, V = (n) => {
+  var t, e;
+  if (!n) return;
+  const r = n.split(`
+`), o = r.findIndex(
+    (v) => v.includes("api.setState")
+  );
+  if (o < 0) return;
+  const l = ((t = r[o + 1]) == null ? void 0 : t.trim()) || "";
+  return (e = /.+ (.+) .+/.exec(l)) == null ? void 0 : e[1];
+}, W = (n, t = {}) => (e, r, o) => {
+  const { enabled: l, anonymousActionType: v, store: s, ...p } = t;
+  let f;
+  try {
+    f = (l ?? (R ? "production" : void 0) !== "production") && window.__REDUX_DEVTOOLS_EXTENSION__;
+  } catch {
+  }
+  if (!f)
+    return n(e, r, o);
+  const { connection: i, ...d } = U(s, f, p);
+  let g = !0;
+  o.setState = ((c, m, a) => {
+    const S = e(c, m);
+    if (!g) return S;
+    const O = a === void 0 ? {
+      type: v || V(new Error().stack) || "anonymous"
+    } : typeof a == "string" ? { type: a } : a;
+    return s === void 0 ? (i?.send(O, r()), S) : (i?.send(
+      {
+        ...O,
+        type: `${s}/${O.type}`
+      },
+      {
+        ...w(p.name),
+        [s]: o.getState()
+      }
+    ), S);
+  }), o.devtools = {
+    cleanup: () => {
+      i && typeof i.unsubscribe == "function" && i.unsubscribe(), z(p.name, s);
+    }
+  };
+  const u = (...c) => {
+    const m = g;
+    g = !1, e(...c), g = m;
+  }, _ = n(o.setState, r, o);
+  if (d.type === "untracked" ? i?.init(_) : (d.stores[d.store] = o, i?.init(
+    Object.fromEntries(
+      Object.entries(d.stores).map(([c, m]) => [
+        c,
+        c === d.store ? _ : m.getState()
+      ])
+    )
+  )), o.dispatchFromDevtools && typeof o.dispatch == "function") {
+    let c = !1;
+    const m = o.dispatch;
+    o.dispatch = (...a) => {
+      (R ? "production" : void 0) !== "production" && a[0].type === "__setState" && !c && (console.warn(
+        '[zustand devtools middleware] "__setState" action type is reserved to set state from the devtools. Avoid using it.'
+      ), c = !0), m(...a);
+    };
+  }
+  return i.subscribe((c) => {
+    var m;
+    switch (c.type) {
+      case "ACTION":
+        if (typeof c.payload != "string") {
+          console.error(
+            "[zustand devtools middleware] Unsupported action format"
+          );
+          return;
+        }
+        return E(
+          c.payload,
+          (a) => {
+            if (a.type === "__setState") {
+              if (s === void 0) {
+                u(a.state);
+                return;
+              }
+              Object.keys(a.state).length !== 1 && console.error(
+                `
+                    [zustand devtools middleware] Unsupported __setState action format.
+                    When using 'store' option in devtools(), the 'state' should have only one key, which is a value of 'store' that was passed in devtools(),
+                    and value of this only key should be a state object. Example: { "type": "__setState", "state": { "abc123Store": { "foo": "bar" } } }
+                    `
+              );
+              const S = a.state[s];
+              if (S == null)
+                return;
+              JSON.stringify(o.getState()) !== JSON.stringify(S) && u(S);
+              return;
+            }
+            o.dispatchFromDevtools && typeof o.dispatch == "function" && o.dispatch(a);
+          }
+        );
+      case "DISPATCH":
+        switch (c.payload.type) {
+          case "RESET":
+            return u(_), s === void 0 ? i?.init(o.getState()) : i?.init(w(p.name));
+          case "COMMIT":
+            if (s === void 0) {
+              i?.init(o.getState());
+              return;
+            }
+            return i?.init(w(p.name));
+          case "ROLLBACK":
+            return E(c.state, (a) => {
+              if (s === void 0) {
+                u(a), i?.init(o.getState());
+                return;
+              }
+              u(a[s]), i?.init(w(p.name));
+            });
+          case "JUMP_TO_STATE":
+          case "JUMP_TO_ACTION":
+            return E(c.state, (a) => {
+              if (s === void 0) {
+                u(a);
+                return;
+              }
+              JSON.stringify(o.getState()) !== JSON.stringify(a[s]) && u(a[s]);
+            });
+          case "IMPORT_STATE": {
+            const { nextLiftedState: a } = c.payload, S = (m = a.computedStates.slice(-1)[0]) == null ? void 0 : m.state;
+            if (!S) return;
+            u(s === void 0 ? S : S[s]), i?.send(
+              null,
+              // FIXME no-any
+              a
+            );
+            return;
+          }
+          case "PAUSE_RECORDING":
+            return g = !g;
+        }
+        return;
+    }
+  }), _;
+}, B = W, E = (n, t) => {
+  let e;
+  try {
+    e = JSON.parse(n);
+  } catch (r) {
+    console.error(
+      "[zustand devtools middleware] Could not parse the received json",
+      r
+    );
+  }
+  e !== void 0 && t(e);
+};
+class G extends EventTarget {
+  constructor() {
+    super(...arguments), this.controller = new AbortController();
+  }
+  on(t, e) {
+    return this.addEventListener(
+      t,
+      (r) => e(r.detail),
+      { signal: this.controller.signal }
+    ), this;
+  }
+  once(t, e) {
+    return this.addEventListener(
+      t,
+      (r) => e(r.detail),
+      {
+        signal: this.controller.signal,
+        once: !0
+      }
+    ), this;
+  }
+  emit(t, e) {
+    return this.dispatchEvent(new CustomEvent(t, { detail: e }));
+  }
+  removeAllListeners() {
+    this.controller.abort(), this.controller = new AbortController();
+  }
+}
+const b = new G(), X = J()(B((n, t) => ({
+  loadingCount: 0,
+  overrideState: null,
+  localCounters: {},
+  isLoading() {
+    return t().overrideState ?? t().loadingCount > 0;
+  },
+  actions: {
+    isGlobalLoading() {
+      return t().isLoading();
+    },
+    startLoading: (e) => {
+      const r = t().isLoading();
+      n((l) => ({ loadingCount: l.loadingCount + 1 })), e && n((l) => ({
+        localCounters: {
+          ...l.localCounters,
+          [e]: (l.localCounters[e] ?? 0) + 1
+        }
+      }));
+      const o = t().isLoading();
+      o && !r && b.emit("start", null), b.emit("change", { isLoading: o, isOverrideState: t().overrideState !== null });
+    },
+    stopLoading: (e) => {
+      const r = t().isLoading(), o = e ? t().localCounters[e] ?? 0 : 0;
+      e && o > 0 && n((v) => ({
+        loadingCount: Math.max(0, v.loadingCount - 1),
+        localCounters: {
+          ...v.localCounters,
+          [e]: Math.max(0, v.localCounters[e] - 1)
+        }
+      }));
+      const l = t().isLoading();
+      !l && r && b.emit("stop", null), b.emit("change", { isLoading: l, isOverrideState: t().overrideState !== null });
+    },
+    overrideLoading: (e) => {
+      const r = t().isLoading();
+      n({ overrideState: e });
+      const o = t().isLoading();
+      o && !r ? b.emit("start", null) : !o && r && b.emit("stop", null), b.emit("change", { isLoading: o, isOverrideState: e !== null });
+    },
+    getLocalCounter: (e) => t().localCounters[e] ?? 0,
+    isLocalLoading: (e) => (t().localCounters[e] ?? 0) > 0
+  }
+})));
+function A() {
+  const n = N(), { actions: t } = X((l) => l), e = () => {
+    t.startLoading(n);
+  }, r = () => {
+    t.isLocalLoading(n) && t.stopLoading(n);
+  }, o = async (l) => {
+    e();
+    try {
+      return await l;
+    } finally {
+      r();
+    }
+  };
+  return {
+    overrideLoading: t.overrideLoading,
+    startLoading: e,
+    stopLoading: r,
+    get isLocalLoading() {
+      return t.isLocalLoading(n);
+    },
+    asyncUseLoading: o,
+    get isLoading() {
+      return t.isGlobalLoading();
+    }
+  };
+}
+const h = {
+  Spin: "spin",
+  FadeInOut: "fadeInOut",
+  None: "none"
+}, H = ({ scale: n = 1, animationType: t = h.Spin, animationDuration: e, children: r, style: o, className: l, id: v, prefix: s }) => {
+  const p = t, f = t === h.Spin ? 1 : t === h.FadeInOut ? 2 : 0, i = e || f, d = t === h.Spin ? "linear" : t === h.FadeInOut ? "ease-in-out" : "linear", g = t === h.None ? "none" : `${s}-${p} ${i}s ${d} infinite`;
+  return /* @__PURE__ */ L("div", { style: { animation: g, ...n !== 1 ? { zoom: n } : {}, ...o }, className: l, id: v, children: r });
+}, K = (n) => /* @__PURE__ */ L("div", { id: "loading-circle", style: { width: "90px", height: "90px", border: "15px solid #f3f3f3", borderTop: "15px solid #009b4bff", borderRadius: "50%", boxSizing: "border-box" }, ...n }), q = (n) => /* @__PURE__ */ L("div", { style: { padding: "20px", fontSize: "25px", color: "#333", fontFamily: "system-ui, sans-serif" }, ...n, children: "Please wait..." });
+function tt({
+  loadingComponent: n,
+  loadingComponentScale: t = 1,
+  animationType: e = h.Spin,
+  animationDuration: r,
+  wrapperStyle: o,
+  wrapperClassName: l,
+  wrapperId: v,
+  animationWrapperStyle: s,
+  animationWrapperClassName: p,
+  animationWrapperId: f
+}) {
+  n = n || (e === h.Spin ? K : q);
+  const i = x(Math.random().toString(36).substring(2, 6).replace(/[0-9]/g, "")), { isLoading: d } = A(), g = x(null);
+  k(() => {
+    d ? (g.current?.showModal(), document.body.setAttribute("inert", "")) : (g.current?.close(), document.body.removeAttribute("inert"));
+  }, [d]);
+  const u = v || "loading-wrapper-" + i.current;
+  return d ? F(
+    /* @__PURE__ */ j(D, { children: [
+      /* @__PURE__ */ L("style", { children: `
+                        dialog#${u}[open] {
+                            display: flex !important;
+                            justify-content: center;
+                            align-items: center;
+                            width: 100vw;
+                            height: 100vh;
+                            max-width: 100%;
+                            max-height: 100%;
+                        }
+                        @keyframes ${i.current}-spin {
+                            0% { transform: rotate(0deg); }
+                            100% { transform: rotate(360deg); }
+                        }
+                        @keyframes ${i.current}-fadeInOut {
+                            0%, 100% { opacity: 0.2; }
+                            50% { opacity: 1; }
+                        }
+                        body:has(dialog#${u}[open]) {
+                            overflow: hidden;
+                        }
+                        body {
+                            scrollbar-gutter: stable;
+                        }
+                    ` }),
+      /* @__PURE__ */ L(
+        "dialog",
+        {
+          ref: g,
+          style: {
+            border: "none",
+            padding: 0,
+            backgroundColor: "rgba(0, 0, 0, 0.5)",
+            backdropFilter: "blur(2px)",
+            ...o
+          },
+          className: l,
+          id: u,
+          children: /* @__PURE__ */ L(H, { scale: t, animationType: e, animationDuration: r, style: s, className: p, id: f, prefix: i.current, children: y.isValidElement(n) ? n : y.createElement(n) })
+        }
+      )
+    ] }),
+    document.body
+  ) : null;
+}
+function et({ isLoading: n = !1 }) {
+  const { startLoading: t, stopLoading: e } = A();
+  return k(() => (n ? t() : e(), () => {
+    n && e();
+  }), [n]), null;
+}
+export {
+  h as AnimationType,
+  G as EventEmitter,
+  et as Loading,
+  K as LoadingCircle,
+  q as LoadingPleaseWait,
+  tt as LoadingRenderer,
+  b as loadingEventTarget,
+  A as useLoading
+};

package/dist/utils/EventEmitter.d.ts

@@ -0,0 +1,9 @@
+type EventMap = Record<string, any>;
+export default class EventEmitter<T extends EventMap> extends EventTarget {
+    private controller;
+    on<K extends keyof T>(type: K, callback: (detail: T[K]) => void): this;
+    once<K extends keyof T>(type: K, callback: (detail: T[K]) => void): this;
+    emit<K extends keyof T>(type: K, detail: T[K]): boolean;
+    removeAllListeners(): void;
+}
+export {};

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@rokku-x/react-hook-loading-spinner",
+  "version": "0.1.0",
+  "description": "A lightweight and flexible React loading state hook library with built-in spinner components, global state management, and zero dependencies (except React and Zustand).",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "prepare": "npm run build",
+    "dev": "vite",
+    "preview": "vite preview",
+    "test": "vitest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rokku-x/react-hook-loading-spinner.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rokku-x/react-hook-loading-spinner/issues"
+  },
+  "homepage": "https://github.com/rokku-x/react-hook-loading-spinner#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.0.0",
+    "@testing-library/react": "^14.0.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^5.0.4",
+    "jsdom": "^27.4.0",
+    "typescript": "^5.0.0",
+    "vite": "^7.1.9",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^1.0.0"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "dist/*"
+      ]
+    }
+  },
+  "keywords": [
+    "react",
+    "loading",
+    "spinner",
+    "hook",
+    "state",
+    "component",
+    "library",
+    "zustand",
+    "typescript"
+  ],
+  "author": "rokku-x",
+  "license": "MIT",
+  "dependencies": {
+    "zustand": "^5.0.10"
+  }
+}