Closes #1241: Add wsConnecting event (#1248)

* Closes #1241: Add wsConnecting event

* Remove redundant tests

(The separate tests for connecting, open, and close events are handled by the one lifecycle event test which both tests that the events are called as expected and in the order expected.)

* Add event.type to detail object of wsConnecting event

(This makes the event polymorphic for this property path with the other lifecycle events – wsOpen and wsClose – which proxy the underlying socket’s event object. This means all lifecycle events can be handled by one handler – e.g., a status indication function – if desired.)

* Minor: Add missing semicolon

* Document wsConnecting event

(And fix two tiny grammar issues.)

src/ext/ws.js

@@ -247,6 +247,11 @@ This extension adds support for WebSockets to htmx.  See /www/extensions/ws.md f
 				/** @type {WebSocket} */
 				var socket = socketFunc();
 
+				// The event.type detail is added for interface conformance with the
+				// other two lifecycle events (open and close) so a single handler method
+				// can handle them polymorphically, if required.
+				api.triggerEvent(socketElt, "htmx:wsConnecting", { event: { type: 'connecting' } });
+
 				this.socket = socket;
 
 				socket.onopen = function (e) {

test/ext/ws.js

@@ -81,43 +81,38 @@ describe("web-sockets extension", function () {
         var div = make('<div hx-ext="ws" ws-connect="ws://localhost:8080"><div id="d1">div1</div><div id="d2">div2</div></div>');
         this.tickMock();
 
-        this.socketServer.emit('message', "<div id=\"d1\">replaced</div>")
+        this.socketServer.emit('message', "<div id=\"d1\">replaced</div>");
 
         this.tickMock();
         byId("d1").innerHTML.should.equal("replaced");
         byId("d2").innerHTML.should.equal("div2");
     })
 
-    it('raises event when socket connected', function () {
-        var myEventCalled = false;
-        var handler = function (evt) {
-            myEventCalled = true;
-        };
-        htmx.on("htmx:wsOpen", handler)
+    it('raises lifecycle events (connecting, open, close) in correct order', function () {
+        var handledEventTypes = [];
+        var handler = function (evt) { handledEventTypes.push(evt.detail.event.type) };
 
-        make('<div hx-ext="ws" ws-connect="ws://localhost:8080">');
-        this.tickMock();
-        myEventCalled.should.be.true;
-        htmx.off("htmx:wsOpen", handler)
-    })
-
-    it('raises event when socket closed', function () {
-        var myEventCalled = false;
-        var handler = function (evt) {
-            myEventCalled = true;
-        };
+        htmx.on("htmx:wsConnecting", handler);
 
         var div = make('<div hx-get="/test" hx-swap="outerHTML" hx-ext="ws" ws-connect="ws://localhost:8080">');
-        htmx.on(div, "htmx:wsClose", handler)
+
+        htmx.on(div, "htmx:wsOpen", handler);
+        htmx.on(div, "htmx:wsClose", handler);
+
         this.tickMock();
 
         div.parentElement.removeChild(div);
-
         this.socketServer.emit('message', 'foo');
+
         this.tickMock();
-        myEventCalled.should.be.true;
+
+        handledEventTypes.should.eql(['connecting', 'open', 'close']);
+
         this.tickMock();
-        htmx.off(div, "htmx:wsClose", handler)
+
+        htmx.off("htmx:wsConnecting", handler);
+        htmx.off(div, "htmx:wsOpen", handler);
+        htmx.off(div, "htmx:wsClose", handler);
     })
 
     it('raises htmx:wsConfig when sending, allows message modification', function () {

www/extensions/web-sockets.md

@@ -111,9 +111,17 @@ state and sends them once the connection is restored.
 
 WebSockets extensions exposes a set of events that allow you to observe and customize its behavior.
 
+#### <a name="htmx:wsConnecting"></a> Event - [`htmx:wsConnecting`](#htmx:wsConnecting)
+
+This event is triggered when a connection to a WebSocket endpoint is being attempted.
+
+##### Details
+
+* `detail.event.type` - the type of the event (`'connecting'`)
+
 #### <a name="htmx:wsOpen"></a> Event - [`htmx:wsOpen`](#htmx:wsOpen)
 
-This event is triggered when a connection to WebSockets endpoint has been established.
+This event is triggered when a connection to a WebSocket endpoint has been established.
 
 ##### Details
 
@@ -123,7 +131,7 @@ This event is triggered when a connection to WebSockets endpoint has been establ
 
 #### <a name="htmx:wsClose"></a> Event - [`htmx:wsClose`](#htmx:wsClose)
 
-This event is triggered when a connection to WebSockets endpoint has been closed normally.
+This event is triggered when a connection to a WebSocket endpoint has been closed normally.
 You can check if the event was caused by an error by inspecting `detail.event` property.
 
 ##### Details