feat: TimeoutController - a utility controller that fires an event af…

…ter x seconds to wire up to other controllers

dist/controllers/utility/timeout_controller.d.ts

@@ -0,0 +1,13 @@
+import { BaseController } from "../../utilities/base_controller";
+export declare class TimeoutController extends BaseController {
+    static values: {
+        seconds: NumberConstructor;
+    };
+    readonly secondsValue: number;
+    _timeoutHandle: null | number;
+    initialize(): void;
+    connect(): void;
+    disconnect(): void;
+    _timeout(): void;
+}
+//# sourceMappingURL=timeout_controller.d.ts.map

dist/index.d.ts

@@ -39,6 +39,7 @@ export { StickyController } from "./controllers/sticky_controller";
 export { TableSortController } from "./controllers/tables/table_sort_controller";
 export { TableTruncateController } from "./controllers/tables/table_truncate_controller";
 export { TeleportController } from "./controllers/teleport_controller";
+export { TimeoutController } from "./controllers/utility/timeout_controller";
 export { ToggleClassController } from "./controllers/toggle_class_controller";
 export { TurboFrameRCController } from "./controllers/turbo_frame_rc_controller";
 export { TurboFrameRefreshController } from "./controllers/turbo_frame_refresh_controller";

docs/docs/controllers/timeout_controller.mdx

@@ -0,0 +1,57 @@
+---
+id: TimeoutController
+title: TimeoutController
+---
+
+
+
+
+
+import NoActions from "../_partials/no-actions.md";
+import NoTargets from "../_partials/no-targets.md";
+import NoClasses from "../_partials/no-classes.md";
+
+## Purpose
+
+Utility controller to wire up other controller actions that need to fire after an elapsed time.
+
+## [Actions](https://stimulus.hotwire.dev/reference/actions)
+
+<NoActions/>
+
+## [Targets](https://stimulus.hotwire.dev/reference/targets)
+
+<NoTargets/>
+
+## [Classes](https://stimulus.hotwire.dev/reference/classes)
+
+<NoClasses/>
+
+## [Values](https://stimulus.hotwire.dev/reference/values)
+
+| Value | Type | Description | Default |
+| --- | --- | --- | --- |
+| `seconds` | Number | The number of seconds until the action fires | - |
+
+## Events
+
+| Event | When | Dispatched on | `event.detail` |
+| --- | --- |--- | --- |
+|`timeout:action` | Fired after `secondsValue` seconds, used to wire your desired controller actions to | the controller root element | `element`: the controller root element |
+
+## Side Effects
+
+Calls `setTimeout` with the desired timeout. Cleans up on disconnect if that happens before timeout occurs.
+
+# How to Use
+
+An example: Show a marketing popup after 30 seconds.
+
+```html
+<div data-controller="popup dismissable" data-action="timeout:action->popup#open">
+  <meta data-controller="timeout" data-timeout-seconds-value="30" />
+  <p>Sign up to get great deals!</p>
+
+  <a data-action="click->dismissable#dismiss">No thanks</a>
+</div>
+```

docs/sidebars.js

@@ -58,6 +58,7 @@ module.exports = {
         "Utility Controllers": [
           "controllers/AppearanceController",
           "controllers/IntersectionController",
+          "controllers/TimeoutController",
         ],
       },
       {

src/controllers/utility/timeout_controller.ts

@@ -0,0 +1,30 @@
+import {BaseController} from "../../utilities/base_controller";
+
+export class TimeoutController extends BaseController {
+
+  static values = {seconds: Number};
+
+  declare readonly secondsValue: number;
+  _timeoutHandle: null | number = null;
+
+  initialize() {
+    this._timeout = this._timeout.bind(this);
+  }
+
+  connect() {
+    requestAnimationFrame(() => {
+      this._timeoutHandle = window.setTimeout(this._timeout, this.secondsValue * 1000);
+    });
+  }
+
+  disconnect() {
+    if (this._timeoutHandle) {
+      window.clearTimeout(this._timeoutHandle);
+    }
+  }
+
+  _timeout() {
+    this.dispatch(this.el, "timeout");
+  }
+
+}

src/index.ts

@@ -39,6 +39,7 @@ export {StickyController} from "./controllers/sticky_controller";
 export {TableSortController} from "./controllers/tables/table_sort_controller";
 export {TableTruncateController} from "./controllers/tables/table_truncate_controller";
 export {TeleportController} from "./controllers/teleport_controller";
+export {TimeoutController} from "./controllers/utility/timeout_controller";
 export {ToggleClassController} from "./controllers/toggle_class_controller";
 export {TurboFrameRCController} from "./controllers/turbo_frame_rc_controller";
 export {TurboFrameRefreshController} from "./controllers/turbo_frame_refresh_controller";