@solid-primitives/event-listener - npm Package Compare versions

Comparing version 1.3.5 to 1.3.6

package.json

 {
   "name": "@solid-primitives/event-listener",
-  "version": "1.3.5",
+  "version": "1.3.6",
   "description": "Primitive to manage creating event listeners.",
@@ -16,20 +16,25 @@ "author": "David Di Biase <[e-mail]>",
     "list": [
-      "createEventListener"
+      "createEventListener",
+      "createEventSignal",
+      "createEventListenerMap",
+      "createEventStore",
+      "WindowEventListener",
+      "DocumentEventListener"
     ],
     "category": "Browser APIs"
   },
+  "private": false,
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
-  "private": false,
-  "sideEffects": false,
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "scripts": {
-    "prebuild": "npm run clean",
-    "clean": "rimraf dist/",
+    "start": "vite -r ./dev/ -c ./dev/vite.config.ts",
     "build": "tsup",
-    "test": "uvu -r solid-register"
+    "test": "uvu -r solid-register",
+    "watch-test": "watchlist src test -- npm test"
   },
@@ -43,13 +48,19 @@ "keywords": [
   "devDependencies": {
-    "jsdom": "^18.1.1",
+    "jsdom": "^19.0.0",
     "prettier": "^2.5.0",
-    "solid-register": "^0.1.1",
+    "solid-register": "0.0.18",
     "tslib": "^2.3.1",
-    "tsup": "^5.10.1",
-    "typescript": "^4.5.2",
-    "uvu": "^0.5.2"
+    "tsup": "^5.10.0",
+    "unocss": "^0.12.4",
+    "uvu": "^0.5.2",
+    "vite": "2.6.14",
+    "vite-plugin-solid": "2.1.2",
+    "watchlist": "^0.3.1"
   },
   "peerDependencies": {
     "solid-js": "^1.2.5"
+  },
+  "dependencies": {
+    "@solid-primitives/utils": "^0.0.255"
   }
 }

README.md

@@ -6,5 +6,13 @@ # @solid-primitives/event-listener
 [![size](https://img.shields.io/npm/v/@solid-primitives/event-listener?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/event-listener)
+[![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fdavedbase%2Fsolid-primitives%2Fstage-badges%2Fassets%2Fbadges%2Fstage-3.json)](https://github.com/davedbase/solid-primitives#contribution-process)
 
-A helpful event listener primitive that binds window and any element supplied.
+A set of primitives that help with listening to DOM and Custom Events.
 
+- [`createEventListener`](#createEventListener) - Very basic and straightforward primitive that handles multiple elements according to a single event binding.
+- [`createEventSignal`](#createEventListener) - Like `createEventListener`, but events are handled with the returned signal, instead of with a callback.
+- [`createEventListenerMap`](#createEventListenerMap) - A helpful primitive that listens to a map of events. Handle them by individual callbacks.
+- [`createEventStore`](#createEventStore) - Similar to `createEventListenerMap`, but provides a reactive store with the latest captured events.
+- [`WindowEventListener`](#WindowEventListener) - Listen to the `window` DOM Events, using a component.
+- [`DocumentEventListener`](#DocumentEventListener) - The same as [`WindowEventListener`](#WindowEventListener), but listens to `document` events.
+
 ## Installation
@@ -18,25 +26,280 @@
 
-## How to use it
+## `createEventListener`
 
-### createEventListener
+Can be used to listen to DOM or Custom Events on window, document, list of HTML elements or any EventTarget. The target prop can be reactive.
 
-A very straightforward primitive that handles multiple elements according to a single event binding.
+### How to use it
 
 ```ts
-const [add, remove] = createEventListener(document.getElementById("mybutton"), "mouseDown", () =>
-  console.log("Click")
+import { createEventListener } from "@solid-primitives/event-listener";
+
+const clear = createEventListener(
+  document.getElementById("myButton"),
+  "mousemove",
+  e => console.log("x:", e.pageX, "y:", e.pageY),
+  { passive: true }
 );
+
+// to clear all of the event listeners
+clear();
+
+// target element, event name and options can be reactive signals
+const [ref, setRef] = createSignal<HTMLElement>();
+const [name, setName] = createSignal("mousemove");
+const [options, setOptions] = createSignal({ passive: true });
+createEventListener(ref, name, e => {}, options);
+
+// you can provide your own event map type as well:
+// fill both type generics for the best type support
+createEventListener<{ myCustomEvent: MyEvent; other: Event }, "myCustomEvent">(
+  window,
+  "myCustomEvent",
+  () => console.log("yup!")
+);
+// just don't use interfaces as EventMaps! (write them using `type` keyword)
 ```
 
-### Directive
+### Directive Usage
 
+props passed to the directive are also reactive, so you can change handlers on the fly.
+
+```tsx
+import { eventListener } from "@solid-primitives/event-listener";
+// avoids tree-shaking the directive:
+eventListener;
+
+<button use:eventListener={["click", () => console.log("Click")]}>Click!</button>;
+```
+
+### Types
+
 ```ts
-<button use:createEventListener={() => ["click", () => console.log("Click")]}>Click!</button>;
-// you can provide your own event map type as well:
-createEventListener<{ myCustomEvent: Event }>(window, "myCustomEvent", () => console.log("yup!"));
+function createEventListener<
+  EventMap extends Record<string, Event>,
+  EventName extends keyof EventMap
+>(
+  target: MaybeAccessor<Many<EventTarget>>,
+  eventName: MaybeAccessor<EventName>,
+  handler: (event: EventMap[EventName]) => void,
+  options?: MaybeAccessor<boolean | AddEventListenerOptions>
+): ClearListeners;
+
+// Directive
+function eventListener(
+  target: Element,
+  props: Accessor<EventListenerDirectiveProps>
+): EventListenerReturn;
+
+type EventListenerDirectiveProps = [
+  name: string,
+  handler: (e: any) => void,
+  options?: AddEventListenerOptions | boolean
+];
 ```
 
+## `createEventSignal`
+
+Like [`createEventListener`](#createEventListener), but events are handled with the returned signal, instead of with a callback.
+
+### How to use it
+
+```ts
+import { createEventSignal } from "@solid-primitives/event-listener";
+
+// all arguments can be reactive signals
+const [lastEvent, clear] = createEventSignal(el, "mousemove", { passive: true });
+
+createEffect(() => {
+  console.log(lastEvent()?.x, lastEvent()?.y);
+});
+
+// to clear all the event listeners
+clear();
+```
+
+### Types
+
+```ts
+function createEventSignal<
+  EventMap extends Record<string, Event>,
+  EventName extends keyof EventMap = keyof EventMap
+>(
+  target: MaybeAccessor<Many<EventTarget>>,
+  eventName: MaybeAccessor<EventName>,
+  options?: MaybeAccessor<boolean | AddEventListenerOptions>
+): EventListenerSignalReturns<EventMap[EventName]>;
+
+type EventListenerSignalReturns<Event> = [
+  lastEvent: Accessor<Event | undefined>,
+  clear: ClearListeners
+];
+```
+
+## `createEventListenerMap`
+
+A helpful primitive that listens to a map of events. Handle them by individual callbacks.
+
+### How to use it
+
+```ts
+import { createEventListenerMap } from "@solid-primitives/event-listener";
+
+const clear = createEventListenerMap(element, {
+  mousemove: mouseHandler,
+  mouseenter: e => {},
+  touchend: touchHandler
+});
+
+// to clear all the event listeners
+clear();
+
+// both target and options args can be reactive:
+const [target, setTarget] = createSignal(document.getElementById("abc"));
+const [options, setOptions] = createSignal({ passive: true });
+createEventListenerMap(
+  target,
+  {
+    mousemove: e => {},
+    touchstart: e => {}
+  },
+  options
+);
+
+// createEventListenerMap can be used to listen to custom events
+// fill both type generics for the best type support
+createEventListenerMap<
+  {
+    myEvent: MyEvent;
+    custom: Event;
+    other: Event;
+  },
+  "myEvent" | "custom"
+>(target, {
+  myEvent: e => {},
+  custom: e => {}
+});
+```
+
+### Directive usage
+
+```tsx
+import { eventListenerMap } from "@solid-primitives/event-listener";
+// prevent tree-shaking:
+eventListenerMap;
+
+<div
+  use:eventListenerMap={{
+    mousemove: e => {},
+    click: clickHandler,
+    touchstart: () => {},
+    myCustomEvent: e => {}
+  }}
+></div>;
+```
+
+### Types
+
+```ts
+function createEventListenerMap<
+  EventMap extends Record<string, Event>,
+  UsedEvents extends keyof EventMap = keyof EventMap
+>(
+  target: MaybeAccessor<Many<EventTarget>>,
+  handlersMap: EventHandlersMap,
+  options?: MaybeAccessor<boolean | AddEventListenerOptions>
+): ClearListeners;
+```
+
+## `createEventStore`
+
+Similar to [`createEventListenerMap`](#createEventListenerMap), but provides a reactive store with the latest captured events.
+
+### How to use it
+
+```ts
+const [lastEvents, clear] = createEventStore(el, "mousemove", "touchend", "click");
+
+createEffect(() => {
+  console.log(lastEvents?.mousemove.x);
+});
+
+// to clear all the event listeners
+clear()
+
+// both target and options args can be reactive:
+const [target, setTarget] = createSignal(document.getElementById("abc"));
+const [options, setOptions] = createSignal({ passive: true });
+const [lastEvents] = createEventStore(target, options, "mousemove", "touchmove");
+
+// createEventStore can be used to listen to custom events
+// fill both type generics for the best type support
+const [lastEvents] = createEventStore<
+  {
+    myEvent: MyEvent;
+    custom: Event;
+    unused: Event;
+  },
+  "myEvent" | "custom"
+>(target, "myEvent", "custom");
+
+// DON'T DO THIS:
+const [{ mousemove }] = createEventStore(target, "mousemove", ...);
+// the store cannot be destructured
+```
+
+### types
+
+```ts
+function createEventStore<
+  EventMap extends Record<string, Event>,
+  UsedEvents extends keyof EventMap = keyof EventMap
+>(
+  target: MaybeAccessor<Many<EventTarget>>,
+  ...eventNames: UsedEvents[]
+): EventListnenerStoreReturns<Pick<EventMap, UsedEvents>>;
+
+// with options:
+function createEventStore<
+  EventMap extends Record<string, Event>,
+  UsedEvents extends keyof EventMap = keyof EventMap
+>(
+  target: MaybeAccessor<Many<EventTarget>>,
+  options: MaybeAccessor<boolean | AddEventListenerOptions>,
+  ...eventNames: UsedEvents[]
+): EventListnenerStoreReturns<Pick<EventMap, UsedEvents>>;
+
+type EventListnenerStoreReturns<E> = [lastEvents: Store<Partial<E>>, clear: ClearListeners];
+```
+
+## `WindowEventListener`
+
+Listen to the `window` DOM Events, using a component.
+
+You can use it with any Solid's Control-Flow components, e.g. `<Show/>` or `<Switch/>`.
+
+The event handler prop is reactive, so you can use it with signals.
+
+### How to use it
+
+```tsx
+import { WindowEventListener } from "@solid-primitives/event-listener";
+
+<WindowEventListener onMouseMove={e => console.log(e.x, e.y)} />;
+```
+
+## `DocumentEventListener`
+
+The same as [`WindowEventListener`](#WindowEventListener), but listens to `document` events.
+
+### How to use it
+
+```tsx
+import { DocumentEventListener } from "@solid-primitives/event-listener";
+
+<DocumentEventListener onMouseMove={e => console.log(e.x, e.y)} />;
+```
+
 ## Demo
 
-You may view a working example here: https://codesandbox.io/s/solid-primitives-event-listener-8mm77
+You may view a working example here: https://codesandbox.io/s/solid-primitives-event-listener-elti5
 
@@ -68,2 +331,7 @@ ## Changelog
 
+1.3.0
+
+**(minor breaking changes to type generics and returned functions)**
+Primitive rewritten to provide better types and more solidlike (reactive) usage. Added a lot more primitives.
+
 </details>

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

18353

increased by78.62%

Number of lines in readme file

335

increased by400%

Number of medium supply chain risk alerts

0

decreased by-100%

Worsened metrics

Dependency count

2

increased by100%

Dev dependency count

10

increased by42.86%

Dependency changes

• + Added@solid-primitives/utils@^0.0.255

• + Added@solid-primitives/utils@0.0.255(transitive)