open-index/open-npm huggingface dataset:
npm package: @rafaelolvr/ss-lib
Description: A shareable library for React applications.
Author: Rafael Oliveira
Latest version: 1.0.10

# ss_lib

Library of utility hooks and helpers for React applications.

## Hooks

### `useAudio`

A hook to manage audio playback.

**Signature:**

```typescript
const {
  playing,
  play,
  pause,
  toggle,
  stop,
  volume,
  setVolume
} = useAudio(url: string, loop: boolean = false);
```

**Parameters:**

- `url` (string): The URL of the audio file.
- `loop` (boolean, optional): Whether the audio should loop. Default is `false`.

**Return Values:**

- `playing` (boolean): Current playing state.
- `play` (function): Function to start playback.
- `pause` (function): Function to pause playback.
- `toggle` (function): Function to toggle between play and pause.
- `stop` (function): Function to stop playback and reset time to 0.
- `volume` (number): Current volume (0.0 to 1.0).
- `setVolume` (function): Function to set the volume.

**Example:**

```tsx
import { useAudio } from "@rafaelolvr/ss-lib";

const MyComponent = () => {
  const { play, pause, toggle } = useAudio("./sound.mp3");

  return <button onClick={toggle}>Toggle Sound</button>;
};
```

---

### `useObserve`

A hook to listen for window messages (NUI events).

**Signature:**

```typescript
useObserve<T>(eventName: string, handler: (data: T) => void);
```

**Parameters:**

- `eventName` (string): The name of the event to listen for.
- `handler` (function): Callback function to handle the event data.

**Example:**

```tsx
import { useObserve } from "@rafaelolvr/ss-lib";

interface MyData {
  action: string;
  payload: any;
}

const MyComponent = () => {
  useObserve<MyData>("myEvent", (data) => {
    console.log("Received data:", data);
  });

  return <div>Listening for events...</div>;
};
```

---

### `listen`

A hook to add event listeners to the window or specific elements. It automatically cleans up the listener when the component unmounts.

**Signature:**

```typescript
// For Window events
listen<K extends keyof WindowEventMap>(
  eventName: K,
  handler: (event: WindowEventMap[K]) => void,
  element?: Window
);

// For HTMLElement events
listen<K extends keyof HTMLElementEventMap>(
  eventName: K,
  handler: (event: HTMLElementEventMap[K]) => void,
  element: HTMLElement
);
```

**Parameters:**

- `eventName` (string): The name of the event (e.g., 'keydown', 'click').
- `handler` (function): The event handler function.
- `element` (EventTarget, optional): The element to attach the listener to. Defaults to `window`.

**Example:**

```tsx
import { listen } from "@rafaelolvr/ss-lib";

const MyComponent = () => {
  // Listen for keydown on window
  listen("keydown", (event) => {
    if (event.key === "Escape") {
      console.log("Escape pressed");
    }
  });

  return <div>Press Escape</div>;
};
```