-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #6 from stainless-code/update-readme
Update readme
- Loading branch information
Showing
2 changed files
with
103 additions
and
99 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| --- | ||
| "@stainless-code/react-custom-events": patch | ||
| --- | ||
|
|
||
| rework `README.md` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,151 +1,150 @@ | ||
| # Custom Event Hook Library | ||
| # @stainless-code/react-custom-events | ||
|
|
||
| This library provides utilities to simplify working with custom DOM events in React, allowing you to dispatch and listen for events in a declarative and type-safe manner. | ||
|
|
||
| --- | ||
|
|
||
| ## Features | ||
|
|
||
| - **Type-safe custom event handling**: Define the payload type for your custom events. | ||
| - **Declarative React hooks**: Easily manage event listeners with React’s lifecycle. | ||
| - **Optional hooks customization**: Specify when to start/stop listening and include dependencies for event handling. | ||
|
|
||
| --- | ||
| - Typesafe | ||
| - Reusable | ||
| - Simple API | ||
| - Centralised event dispatcher and listener | ||
|
|
||
| ## Installation | ||
|
|
||
| Install the library via npm or yarn: | ||
| ### npm | ||
|
|
||
| ```bash | ||
| # npm | ||
| npm i @stainless-code/react-custom-events | ||
|
|
||
| # yarn | ||
| yarn add @stainless-code/react-custom-events | ||
|
|
||
| # pnpm | ||
| pnpm add @stainless-code/react-custom-events | ||
|
|
||
| # bun | ||
| bun add @stainless-code/react-custom-events | ||
| npm install @stainless-code/react-custom-events | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## API | ||
|
|
||
| ### `createCustomEvent<Payload>(eventName: string)` | ||
| ### yarn | ||
|
|
||
| Creates a custom event hook and dispatcher for a given event name. | ||
|
|
||
| #### Parameters: | ||
|
|
||
| - `eventName`: The name of the custom event to create. | ||
| ```bash | ||
| yarn add @stainless-code/react-custom-events | ||
| ``` | ||
|
|
||
| #### Returns: | ||
| ### pnpm | ||
|
|
||
| A React hook with the following properties: | ||
| ```bash | ||
| pnpm add @stainless-code/react-custom-events | ||
| ``` | ||
|
|
||
| - **Hook function**: A hook to listen for the custom event. | ||
| - **dispatch(payload, eventInitDict?)**: Dispatches the custom event with the given payload. | ||
| ### bun | ||
|
|
||
| --- | ||
| ```bash | ||
| bun add @stainless-code/react-custom-events | ||
| ``` | ||
|
|
||
| ### Hook: `useCustomEventListener<Payload>` | ||
| ## Usage | ||
|
|
||
| This hook listens for custom events and triggers a callback when the event occurs. | ||
| ### 1. Basic | ||
|
|
||
| #### Parameters: | ||
| ```tsx | ||
| import { createCustomEvent } from "@stainless-code/react-custom-events"; | ||
|
|
||
| 1. `eventName`: The name of the event to listen for. | ||
| 2. `onListen(payload, event)`: Callback invoked with the event payload and the `CustomEvent` object. | ||
| 3. `options?`: (Optional) Object containing: | ||
| - `listen`: A boolean to toggle event listening. | ||
| - `onStartListening`: A callback triggered when the hook starts listening. | ||
| - `onStopListening`: A callback triggered when the hook stops listening. | ||
| 4. `deps?`: (Optional) Dependency list to control re-subscription. | ||
| // Create event | ||
| const useMyEvent = createCustomEvent<string>("my-event"); | ||
|
|
||
| --- | ||
| function MyComponent() { | ||
| // Listen for the event | ||
| useMyEvent((payload) => console.log("Event received with payload:", payload)); | ||
|
|
||
| ## Example Usage | ||
| return ( | ||
| // Dispatch event | ||
| <button onClick={() => useMyEvent.dispatch("hello!")}> | ||
| Dispatch event | ||
| </button> | ||
| ); | ||
| } | ||
| ``` | ||
|
|
||
| ### Creating a Custom Event | ||
| ### 2. With options and dependency list | ||
|
|
||
| ```typescript | ||
| ```tsx | ||
| import { createCustomEvent } from "@stainless-code/react-custom-events"; | ||
| import { useState } from "react"; | ||
|
|
||
| // Create event | ||
| const useMyEvent = createCustomEvent<string>("my-event"); | ||
|
|
||
| function MyComponent() { | ||
| const [enabled, setEnabled] = useState(true); | ||
|
|
||
| // Listen for the event | ||
| useMyEvent( | ||
| (payload, event) => | ||
| console.log("Event received with payload:", payload, event), | ||
| { | ||
| listen: enabled, // Control whether the listener is active | ||
| onStartListening: () => console.log("Started listening"), | ||
| onStopListening: () => console.log("Stopped listening"), | ||
| }, | ||
| [enabled], // Re-subscribe when `enabled` changes | ||
| ); | ||
|
|
||
| return ( | ||
| <> | ||
| <button onClick={() => setEnabled(!enabled)}> | ||
| {enabled ? "Disable" : "Enable"} event listener | ||
| </button> | ||
| <button onClick={() => useMyEvent.dispatch("hello!")}> | ||
| Dispatch event | ||
| </button> | ||
| </> | ||
| ); | ||
| } | ||
| ``` | ||
|
|
||
| // Define a custom event hook with a typed payload | ||
| const useMyEvent = createCustomEvent<{ age: number }>("myCustomEvent"); | ||
| ## Typesafety | ||
|
|
||
| // Dispatch the event | ||
| useMyEvent.dispatch({ age: 28 }); | ||
| ``` | ||
| ```tsx | ||
| const useMyEvent = createCustomEvent<string>("my-event"); | ||
|
|
||
| ### Listening for Custom Events | ||
| // dispatching | ||
| useMyEvent.dispatch("Valid string payload"); // ✅ Correct type | ||
| useMyEvent.dispatch(123); // ❌ TypeScript error: Expected 'string', got 'number' | ||
|
|
||
| ```typescript | ||
| // Listen for the event | ||
| // listening | ||
| useMyEvent((payload) => { | ||
| console.log(`Received age: ${payload.age}`); | ||
| console.log(payload.toUpperCase()); // ✅ Correct method for string | ||
| console.log(payload * 2); // ❌ TypeScript error: 'string' is not a number | ||
| }); | ||
|
|
||
| // Advanced usage with options | ||
| useMyEvent( | ||
| (payload) => console.log(`Received age: ${payload.age}`), | ||
| { | ||
| listen: true, // Start listening immediately | ||
| onStartListening: () => console.log("Started listening"), | ||
| onStopListening: () => console.log("Stopped listening"), | ||
| }, | ||
| [ | ||
| /* dependencies */ | ||
| ], | ||
| ); | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## How It Works | ||
| ## API | ||
|
|
||
| 1. **`createCustomEvent`**: | ||
| ### `createCustomEvent()` | ||
|
|
||
| - Creates a custom event dispatcher and corresponding hook for easy integration. | ||
| - The `dispatch` method triggers a DOM `CustomEvent` with the provided payload. | ||
| Creates a custom event with a given name and returns a hook for listening to it and a `dispatch` function for triggering the event. | ||
|
|
||
| 2. **`useCustomEventListener`**: | ||
| - Handles the lifecycle of adding and removing event listeners in a React-friendly manner. | ||
| - Automatically cleans up listeners when the component unmounts or dependencies change. | ||
| | Parameter | Type | Description | Default | | ||
| | ----------- | -------- | ----------------------------- | ---------- | | ||
| | `eventName` | `string` | The name of the custom event. | (required) | | ||
|
|
||
| --- | ||
| #### Returns | ||
|
|
||
| ## Type Safety | ||
|
|
||
| Leverage TypeScript to enforce strict type checking for your event payloads, ensuring reliability and reducing runtime errors. | ||
| - `useCustomEventListener` with `eventName` prepopulated along with a `dispatch` method to trigger the event and the `eventName` property. | ||
|
|
||
| --- | ||
|
|
||
| ## Example in Context | ||
|
|
||
| ```typescript | ||
| const useUserLoginEvent = createCustomEvent<{ userId: string }>("userLogin"); | ||
| ### `useCustomEventListener()` | ||
|
|
||
| // Dispatch the event | ||
| useUserLoginEvent.dispatch({ userId: "abc123" }); | ||
| Custom hook to listen for a custom event and handle the payload. | ||
|
|
||
| // Listen for the event | ||
| useUserLoginEvent((payload) => | ||
| console.log(`User logged in: ${payload.userId}`), | ||
| ); | ||
| ``` | ||
|
|
||
| --- | ||
| | Parameter | Type | Description | Default | | ||
| | -------------------------- | --------------------------------------------------------- | -------------------------------------------------------- | ------------------ | | ||
| | `eventName` | `string` | The name of the custom event to listen for. | (required) | | ||
| | `onListen` | `(payload: Payload, event: CustomEvent<Payload>) => void` | Callback to handle the event payload and event object. | (required) | | ||
| | `options` (optional) | `Object` | Additional configuration for the event listener. | `{ listen: true }` | | ||
| | `options.listen` | `boolean` | Whether the listener should be active (default: `true`). | `true` | | ||
| | `options.onStartListening` | `() => void` | Callback when the listener starts. | `undefined` | | ||
| | `options.onStopListening` | `() => void` | Callback when the listener stops. | `undefined` | | ||
| | `deps` (optional) | `DependencyList` | Dependency list for re-subscribing to the event. | `undefined` | | ||
|
|
||
| ## Contributing | ||
|
|
||
| Feel free to submit issues or PRs to improve the library! | ||
|
|
||
| --- | ||
|
|
||
| ## License | ||
|
|
||
| [MIT](./LICENSE) |