@solid-primitives/idle - npm Package Compare versions

Comparing version 0.0.105 to 0.1.0

dist/index.d.ts

 import { Accessor } from 'solid-js';
 
 type EventTypeName = keyof HTMLElementEventMap | keyof DocumentEventMap;
+/**
+ * An option object to initialize the timer.
+ */
 interface IdleTimerOptions {
+    /**
+     * The DOM events that will be listened to in order to monitor the user's activity.
+     * @default ['mousemove', 'keydown', 'wheel', 'resize', 'mousedown', 'pointerdown', 'touchstart', 'touchmove', 'visibilitychange']
+     */
     events?: EventTypeName[];
+    /**
+     * DOM element to which the event listeners will be attached.
+     * @default document
+     */
     element?: HTMLElement;
+    /**
+     * Time of user's inactivity in milliseconds before the idle status changes to idle.
+     * This time is extended by the promptTimeout option.
+     * @default 900000 (15 minutes)
+     */
     idleTimeout?: number;
+    /**
+     * To meet the typical use case when we want to prompt the user to check if they are still active, an additional timer starts running right after the idleTimeout expires.
+     * In this time slot, the user is in the prompt phase, whose duration is decided by promptTimeout.
+     * onActive is not fired in this phase, which cn only be interrupted by the methods reset, stop, pause, triggerIdle.
+     * @default 0
+     */
     promptTimeout?: number;
+    /**
+     * Requires the event-listeners to be bound manually by using the start method, instead of on mount.
+     * @default false
+     */
     startManually?: boolean;
+    /**
+     * Callback triggered when the user status passes to idle. When invoked, the last event fired before the prompt phase will be passed as a parameter.
+     * @param {Event} lastEvt - the last event fired before the prompt phase. Events fired in the prompt phase will not count.
+     * @returns {void}
+     * @default () => {}
+     */
     onIdle?: (lastEvt: Event) => void;
+    /**
+     * Callback called when the user resumes activity after having been idle (resuming from prompt phase doesn't trigger `onActive`).
+     * @param {Event} activyEvt - the last event fired before the prompt phase.
+     * @returns {void}
+     * @default () => {}
+     */
     onActive?: (activyEvt: Event) => void;
+    /**
+     * Callback triggered when the idleTimeout timer expires, before declaring the idle status, onPrompt callback is fired, starting the prompt timer.
+     * @param {Event} promptEvt - the last event fired before the prompt phase.
+     * @returns {void}
+     * @default () => {}
+     */
     onPrompt?: (promptEvt: Event) => void;
 }
-interface IdleTimerReturn {
+/**
+ * The instance of the idle timer
+ */
+interface IdleTimer {
+    /**
+     * Shows when the user is idle
+     */
     isIdle: Accessor<boolean>;
+    /**
+     * Tells whether onPrompt has been called or not, and consequently if the promptTimeout countdown has started
+     */
     isPrompted: Accessor<boolean>;
+    /**
+     * Resets timers, doesn't trigger onActive
+     */
     reset: () => void;
+    /**
+     * Adds listeners and starts timers, doesn't trigger onActive
+     */
     start: () => void;
+    /**
+     * Removes listeners and cleans up the timers, doesn't trigger onActive.
+     */
     stop: () => void;
+    /**
+     * Set the idle status to idle and trigger the onIdle callback. Doesn't trigger onActive or onPrompt.
+     */
+    triggerIdle: () => void;
 }
+/**
+ * @deprecated
+ * IdleTimerReturn has been renamed to IdleTimer for clarity and coherence.
+ * Please use IdleTimer instead.
+ */
+type IdleTimerReturn = IdleTimer;
 
 /**
+ * @typedef {Object} IdleTimer
+ * @method isIdle - Shows when the user is idle.
+ * @method isPrompted - Tells whether onPrompt has been called or not, and consequently if the promptTimeout countdown has started
+ * @method reset - Resets timers, doesn't trigger onActive
+ * @method start - Adds listeners and starts timers, doesn't trigger onActive
+ * @method stop - Removes listeners and cleans up the timers, doesn't trigger onActive.
+ * @method triggerIdle - Set the idle status to idle and trigger the onIdle callback. Doesn't trigger onActive or onPrompt.
+ */
+/**
  * A primitive to observe the user's idle state and react to its changes.
- * @param - an objects that takes several variables and callbacks, all of them optionals
- * {
- *    @param params.events: EventTypeName[]`; a list of the DOM events that will be listened to in order to monitor the user's activity. The events must be of `ventTypeName type (that can be imported). It defaults to the events in the EVENTS constant.
- *    @param params.idleTimeout: number; time of user's inactivity in milliseconds before the idle status changes to idle. This time is extended by the promptTimeout option. It defaults to 15 minutes.
- *    @param params.promptTimeout: number; to meet the typical usecase when we want to prompt the user to check if we they are still active, an additional timer starts running right after the idleTimeout expires. In this time slot, the user is in the prompt phase, whose duration is decided by promptTimout. It defaults to 0.
- *    @param params.onActive: (evt: Event) => void; callback called when the user resumes activity after having been idle (resuming from prompt phase doesn't trigger `onActive`). The event that triggered the return to activity is passed as a parameter. It defaults to an empty function.
- *    @param params.onIdle: (evt: Event) => void; callback triggered when the user status passes to idle. When invoked, the last event fired before the prompt phase will be passed as parameter. Events fired in the prompt phase will not count. It defaults to an empty function.
- *    @param params.onPrompt: (evt: Event) => void; when the idleTimeout timer expires, before declaring the idle status, onPrompt callback is fired, starting the prompt timer. When invoked, the last event fired before the prompt phase will be passed as a parameter. It defaults to an empty function.
- *    @param params.element: HTMLElement; DOM element to which the event listeners will be attached. It defaults to document.
- *    @param params.startsManually: boolean; requires the event-listeners to be bound manually by using the start method (see @returns), instead of on mount. It defaults to false.
- * }
- * @returns - returns an object with several methods and accessors
- * {
- *    @returns.isIdle: Accessor<boolean>; shows when the user is idle
- *    @returns.isPrompted: Accessor<boolean>; tells whether params.onPrompt has been called or not, and consequently if the promptTimeout countdown has started
- *    @returns.reset: () => void; resets timers, doesn't trigger onActive.
- *    @returns.start: () => void; adds listeners and starts timers, doesn't trigger onActive.
- *    @returns.stop: () => void; removes listeners and cleans up the timers, doesn't trigger onActive.
- * }
+ * @param {Object} [params={}] {@link IdleTimerOptions} - An options object to initialize the timer.
+ * @param {string[]} [params.events=['mousemove', 'keydown', 'wheel', 'resize', 'mousedown', 'pointerdown', 'touchstart', 'touchmove', 'visibilitychange']] {@link EventTypeName}  - The DOM events that will be listened to in order to monitor the user's activity.
+ * @param {number} [params.idleTimeout=900000] - Time of user's inactivity in milliseconds before the idle status changes to idle. This time is extended by the promptTimeout option.
+ * @param {number} [params.promptTimeout=0] - To meet the typical use case when we want to prompt the user to check if they are still active, an additional timer starts running right after the idleTimeout expires. In this time slot, the user is in the prompt phase, whose duration is decided by promptTimeout. onActive is not fired in this phase, which cn only be interrupted by the methods {@link IdleTimer.reset}, {@link IdleTimer.stop}, {@link IdleTimer.pause}, {@link IdleTimer.triggerIdle}.
+ * @param {function(Event): void} [params.onActive=() => {}] - Callback called when the user resumes activity after having been idle (resuming from prompt phase doesn't trigger `onActive`). The event that triggered the return to activity is passed as a parameter.
+ * @param {function(Event): void} [params.onIdle=() => {}] - Callback triggered when the user status passes to idle. When invoked, the last event fired before the prompt phase will be passed as a parameter. Events fired in the prompt phase will not count.
+ * @param {function(Event): void} [params.onPrompt=() => {}] - When the idleTimeout timer expires, before declaring the idle status, onPrompt callback is fired, starting the prompt timer. When invoked, the last event fired before the prompt phase will be passed as a parameter.
+ * @param {HTMLElement} [params.element=document] - DOM element to which the event listeners will be attached.
+ * @param {boolean} [params.startManually=false] - Requires the event-listeners to be bound manually by using the start method (see {@link IdleTimer}), instead of on mount.
+ * @returns {IdleTimer} - The instance of the idle timer. It contains the following accessors and methods:
+ *    - isIdle: Accessor<boolean>; shows when the user is idle
+ *    - isPrompted: Accessor<boolean>; tells whether params.onPrompt has been called or not, and consequently if the promptTimeout countdown has started
+ *    - reset: () => void; resets timers, doesn't trigger onActive
+ *    - start: () => void; adds listeners and starts timers, doesn't trigger onActive
+ *    - stop: () => void; removes listeners and cleans up the timers, doesn't trigger onActive
  */
-declare const createIdleTimer: ({ element, events, idleTimeout, promptTimeout, onActive, onIdle, onPrompt, startManually, }?: IdleTimerOptions) => IdleTimerReturn;
+declare const createIdleTimer: ({ element, events, idleTimeout, promptTimeout, onActive, onIdle, onPrompt, startManually, }?: IdleTimerOptions) => IdleTimer;
 
-export { EventTypeName, IdleTimerOptions, IdleTimerReturn, createIdleTimer };
+export { EventTypeName, IdleTimer, IdleTimerOptions, IdleTimerReturn, createIdleTimer };

dist/index.js

@@ -38,2 +38,4 @@ import { createSignal, onMount, onCleanup, batch } from 'solid-js';
       stop: () => {
+      },
+      triggerIdle: () => {
       }
@@ -127,2 +129,8 @@ };
   }
+  function triggerIdle() {
+    stopListening();
+    setIsIdle(true);
+    onIdle?.(new CustomEvent("manualidle"));
+    addListeners();
+  }
   onMount(() => {
@@ -139,3 +147,4 @@ if (startManually)
     reset: () => timerReset(new CustomEvent("manualreset")),
-    stop: stopListening
+    stop: stopListening,
+    triggerIdle
   };
@@ -142,0 +151,0 @@ };

package.json

 {
   "name": "@solid-primitives/idle",
-  "version": "0.0.105",
+  "version": "0.1.0",
   "description": "A primitive to observe the user's idle status and react to its changes.",
@@ -52,10 +52,12 @@ "author": "Aylo Srd <[e-mail]>",
   "typesVersions": {},
+  "devDependencies": {
+    "solid-js": "^1.8.6"
+  },
   "scripts": {
-    "start": "vite serve dev --host",
-    "dev": "vite serve dev",
-    "page": "vite build dev",
-    "build": "jiti ../../scripts/build.ts",
-    "test": "vitest -c ../../configs/vitest.config.ts",
-    "test:ssr": "pnpm run test --mode ssr"
+    "dev": "tsx ../../scripts/dev.ts",
+    "build": "tsx ../../scripts/build.ts",
+    "vitest": "vitest -c ../../configs/vitest.config.ts",
+    "test": "pnpm run vitest",
+    "test:ssr": "pnpm run vitest --mode ssr"
   }
 }

README.md

@@ -56,2 +56,3 @@ <p>
 - **start**, **stop** and **reset**: `() => void`; allow rispectively to start and stop the timers, and to reset them. `start` and `reset`, create a custom `manualstart` and `manualreset` event, that will be passed to the `onIdle` and `onPrompt` callbacks if no oher activity occurs (there's another custom event, `mount`, created when timers start automatically). Finally `stop` and `reset` don't trigger `onActive`.
+- **triggerIdle**: `() => void`; manually sets `isIdle` to true, and triggers the `onIdle` callback, passing a custom `manualidle` event. It doesn't trigger `onActive` or `onPrompt`.
 
@@ -58,0 +59,0 @@ ### Configuration options

No alert changes

Improved metrics

Total package byte prevSize

31385

increased by84.95%

Number of package files

8

increased by33.33%

Lines of code

565

increased by75.47%

Number of lines in readme file

83

increased by1.22%

Worsened metrics

Dev dependency count

1

increased byInfinity%

No dependency changes