finishing updates

- return clear function form event-listener primitives
- update readme
- update mouse and active-element to last event-listener changes

Author: thetarnav

packages/active-element/README.md

@@ -24,17 +24,20 @@ A reactive `document.activeElement`. Check which element is currently focused.
 ```ts
 import { createActiveElement } from "@solid-primitives/active-element";
 
-const [activeEl, { stop, start }] = createActiveElement();
-// "stop" and "start" are for adding and removing event listeners
+const [activeEl, clear] = createActiveElement();
+
+createEffect(() => {
+  console.log(activeEl());
+});
+
+// clear all event listeners
+clear();
 ```
 
 ### Types
 
 ```ts
-function createActiveElement(): [
-  getter: Accessor<null | Element>,
-  actions: { stop: Fn; start: Fn }
-];
+function createActiveElement(): [getter: Accessor<null | Element>, clear: ClearListeners];
 ```
 
 ## `createIsElementActive`
@@ -46,14 +49,17 @@ Pass in an element, and see if it's focused.
 ```ts
 import { createIsElementActive } from "@solid-primitives/active-element";
 
-const [isFocused, { stop, start }] = createIsElementActive(() => el);
+const [isFocused, clear] = createIsElementActive(() => el);
 // "stop" and "start" are for adding and removing event listeners
 
 // you can also use signals for ref
 const [ref, setRef] = createSignal<Element>();
 const [isFocused] = createIsElementActive(ref);
 // this way if the element changes,
 // the "isFocused" will start checking the new element
+
+// clear all event listeners
+clear();
 ```
 
 ### As Directive
@@ -73,7 +79,7 @@ const [active, setActive] = createSignal(false)
 ```ts
 function createIsElementActive(
   target: MaybeAccessor<Element>
-): [getter: Accessor<boolean>, actions: { stop: Fn; start: Fn }];
+): [getter: Accessor<boolean>, clear: ClearListeners];
 
 type IsElementActiveProps = (isActive: boolean) => void;
 ```

packages/active-element/package.json

@@ -62,7 +62,7 @@
     "solid-js": "^1.2.5"
   },
   "dependencies": {
-    "@solid-primitives/event-listener": "^1.3.0",
-    "@solid-primitives/utils": "^0.0.250"
+    "@solid-primitives/event-listener": "^1.3.2",
+    "@solid-primitives/utils": "^0.0.255"
   }
 }

packages/active-element/src/common.ts

@@ -1,6 +1,6 @@
+import { ClearListeners, createEventListenerMap } from "@solid-primitives/event-listener";
 import { access, Fn, MaybeAccessor, createCallbackStack } from "@solid-primitives/utils";
 import { Accessor, createComputed, createEffect, createSignal, JSX } from "solid-js";
-import { addListener } from "./common";
 
 export type IsElementActiveProps = (isActive: boolean) => void;
 declare module "solid-js" {
@@ -20,10 +20,7 @@ export type E = JSX.Element;
  * @example
  * const [activeEl, { stop, start }] = createActiveElement()
  */
-export function createActiveElement(): [
-  getter: Accessor<null | Element>,
-  actions: { stop: Fn; start: Fn }
-] {
+export function createActiveElement(): [getter: Accessor<null | Element>, clear: ClearListeners] {
   const [active, setActive] = createSignal<Element | null>(null);
   const handleChange = () => setActive(window.document.activeElement);
 
@@ -32,19 +29,12 @@ export function createActiveElement(): [
     toCleanup.execute();
     handleChange();
     toCleanup.push(
-      addListener(window, "blur", handleChange),
-      addListener(window, "focus", handleChange)
+      createEventListenerMap(window, { blur: handleChange, focus: handleChange }, true)
     );
   };
   start();
 
-  return [
-    active,
-    {
-      stop: toCleanup.execute,
-      start
-    }
-  ];
+  return [active, toCleanup.execute];
 }
 
 /**
@@ -56,7 +46,7 @@ export function createActiveElement(): [
  */
 export function createIsElementActive(
   target: MaybeAccessor<Element>
-): [getter: Accessor<boolean>, actions: { stop: Fn; start: Fn }] {
+): [getter: Accessor<boolean>, clear: ClearListeners] {
   const [isActive, setIsActive] = createSignal(false);
   const handleFocus = () => setIsActive(true);
   const handleBlur = () => setIsActive(false);
@@ -67,15 +57,15 @@ export function createIsElementActive(
     const el = access(target);
     if (!el) return setIsActive(false);
     setIsActive(window.document.activeElement === el);
-    toCleanup.push(addListener(el, "blur", handleBlur), addListener(el, "focus", handleFocus));
+    toCleanup.push(createEventListenerMap(el, { blur: handleBlur, focus: handleFocus }, true));
   };
 
   const el = access(target);
   setIsActive(!!el && window.document.activeElement === el);
 
   createEffect(start);
 
-  return [isActive, { stop: toCleanup.execute, start }];
+  return [isActive, toCleanup.execute];
 }
 
 /**

packages/active-element/src/index.ts

@@ -7,15 +7,14 @@ const cae = suite("createActiveElement");
 
 cae("returns correct values", () =>
   createRoot(dispose => {
-    const [activeEl, { stop, start }] = createActiveElement();
+    const [activeEl, stop] = createActiveElement();
 
     assert.type(activeEl, "function");
     assert.ok(
       () => activeEl() === null || activeEl() === document.body,
       "no element should be active"
     );
     assert.type(stop, "function");
-    assert.type(start, "function");
 
     dispose();
   })
@@ -28,12 +27,11 @@ const iea = suite("createIsElementActive");
 iea("returns correct values", () =>
   createRoot(dispose => {
     const el = document.createElement("div");
-    const [isFocused, { stop, start }] = createIsElementActive(el);
+    const [isFocused, stop] = createIsElementActive(el);
 
     assert.type(isFocused, "function");
     assert.is(isFocused(), false);
     assert.type(stop, "function");
-    assert.type(start, "function");
 
     dispose();
   })
@@ -42,12 +40,11 @@ iea("returns correct values", () =>
 iea("target can be an accessor", () =>
   createRoot(dispose => {
     const el = document.createElement("div");
-    const [isFocused, { stop, start }] = createIsElementActive(() => el);
+    const [isFocused, stop] = createIsElementActive(() => el);
 
     assert.type(isFocused, "function");
     assert.is(isFocused(), false);
     assert.type(stop, "function");
-    assert.type(start, "function");
 
     dispose();
   })

packages/active-element/test/index.test.ts

@@ -4,7 +4,7 @@
 [![size](https://img.shields.io/bundlephobia/minzip/@solid-primitives/event-listener?style=for-the-badge)](https://bundlephobia.com/package/@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)
 
-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.
@@ -30,13 +30,16 @@ Can be used to listen to DOM or Custom Events on window, document, list of HTML
 ```ts
 import { createEventListener } from "@solid-primitives/event-listener";
 
-createEventListener(
-  document.getElementById("mybutton"),
+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");
@@ -71,7 +74,7 @@ function createEventListener<
   eventName: MaybeAccessor<EventName>,
   handler: (event: EventMap[EventName]) => void,
   options?: MaybeAccessor<boolean | AddEventListenerOptions>
-): void;
+): ClearListeners;
 
 // Directive
 function eventListener(
@@ -96,11 +99,32 @@ Like [`createEventListener`](#createEventListener), but events are handled with
 import { createEventSignal } from "@solid-primitives/event-listener";
 
 // all arguments can be reactive signals
-const lastEvent = createEventSignal(el, "mousemove", { passive: true });
+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`
@@ -112,12 +136,15 @@ A helpful primitive that listens to a map of events. Handle them by individual c
 ```ts
 import { createEventListenerMap } from "@solid-primitives/event-listener";
 
-createEventListenerMap(element, {
+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 });
@@ -171,7 +198,7 @@ function createEventListenerMap<
   target: MaybeAccessor<Many<EventTarget>>,
   handlersMap: EventHandlersMap,
   options?: MaybeAccessor<boolean | AddEventListenerOptions>
-): void;
+): ClearListeners;
 ```
 
 ## `createEventStore`
@@ -181,19 +208,22 @@ Similar to [`createEventListenerMap`](#createEventListenerMap), but provides a r
 ### How to use it
 
 ```ts
-const lastEvents = createEventStore(el, "mousemove", "touchend", "click");
+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");
+const [lastEvents] = createEventStore(target, options, "mousemove", "touchmove");
 
 // createEventStore can be used to listen to custom events
-const lastEvents = createEventStore<
+const [lastEvents] = createEventStore<
   {
     myEvent: MyEvent;
     custom: Event;
@@ -202,7 +232,7 @@ const lastEvents = createEventStore<
 >(target, "myEvent", "custom");
 
 // DON'T DO THIS:
-const { mousemove } = createEventStore(target, "mousemove", ...);
+const [{ mousemove }] = createEventStore(target, "mousemove", ...);
 // the store cannot be destructured
 ```
 
@@ -215,7 +245,7 @@ function createEventStore<
 >(
   target: MaybeAccessor<Many<EventTarget>>,
   ...eventNames: UsedEvents[]
-): Store<Partial<Pick<EventMap, UsedEvents>>>;
+): EventListnenerStoreReturns<Pick<EventMap, UsedEvents>>;
 
 // with options:
 function createEventStore<
@@ -225,7 +255,9 @@ function createEventStore<
   target: MaybeAccessor<Many<EventTarget>>,
   options: MaybeAccessor<boolean | AddEventListenerOptions>,
   ...eventNames: UsedEvents[]
-): Store<Partial<Pick<EventMap, UsedEvents>>>;
+): EventListnenerStoreReturns<Pick<EventMap, UsedEvents>>;
+
+type EventListnenerStoreReturns<E> = [lastEvents: Store<Partial<E>>, clear: ClearListeners];
 ```
 
 ## `WindowEventListener`
@@ -288,6 +320,6 @@ Migrated to new build process.
 1.3.0
 
 **(minor breaking changes to type generics and returned functions)**
-Primitive rewritten to provide better types and more reliable usage. Added more primitives.
+Primitive rewritten to provide better types and more reliable usage. Added a lot more primitives.
 
 </details>

packages/event-listener/README.md

@@ -46,7 +46,7 @@ const List: Component = () => {
   const [items, setItems] = createSignal<HTMLDivElement[]>([]);
 
   // new event listeners are automatically added to the new items
-  const lastEvent = createEventSignal(items, "click");
+  const [lastEvent] = createEventSignal(items, "click");
 
   return (
     <div class="flex flex-col items-center space-y-6">

packages/event-listener/dev/index.tsx

@@ -14,7 +14,11 @@
     "stage": 3,
     "list": [
       "createEventListener",
-      "GlobalEventListener"
+      "createEventSignal",
+      "createEventListenerMap",
+      "createEventStore",
+      "WindowEventListener",
+      "DocumentEventListener"
     ],
     "category": "Browser APIs"
   },
@@ -55,6 +59,6 @@
     "solid-js": "^1.2.5"
   },
   "dependencies": {
-    "@solid-primitives/utils": "^0.0.250"
+    "@solid-primitives/utils": "^0.0.255"
   }
 }