@excom/network-status 0.1.0

package/support/docs/README.md

@@ -0,0 +1,65 @@
+# network-status
+
+Live connectivity readout — `navigator.onLine` plus connection type and
+speed where the browser exposes them.
+
+<include-content data-demo="simple"></include-content>
+
+## Features
+
+- **CSS-driven UI** Style from `[is-online]` / `[connection-type]`
+- **Live events** `online` / `offline` / `change` fire as connectivity
+  shifts — on transitions, never at mount
+- **Bindable state** `.provision` is the full snapshot; read it from Quark
+  with `prop("provision")`
+- **Network Information API** Connection type + effective speed where
+  supported
+- **Graceful degradation** Unsupported fields stay `null`; core
+  online/offline still works everywhere
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Drop it anywhere and hook `[is-online]` / `[is-mounted]` with CSS, or
+listen for its events from a parent.
+
+```html
+<network-status></network-status>
+```
+
+```css
+network-status:not([is-mounted])::before {
+  content: "Loading…";
+}
+network-status[is-online]::before {
+  content: "📶 Online";
+}
+network-status[is-mounted]:not([is-online])::before {
+  content: "📵 Offline";
+}
+```
+
+Nothing fires at mount: the first read sets `is-online` and `.provision`
+only. React to the attribute (or `prop("provision")`) for the initial
+state; `network-status-online` / `-offline` report transitions.
+
+The Network Information API (`connection-type`, `effective-type`,
+`downlink`, `rtt`) is Chromium-only — Safari and Firefox leave those
+fields `null`. Build critical UX on `is-online` alone; treat the rest as
+a progressive enhancement. Safari/iOS also have known `navigator.onLine`
+reliability quirks — see `INTERNAL.md`.
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Offline banner
+
+A banner shown purely by CSS attribute selector — no listeners needed.
+
+<include-content data-demo="offline-banner"></include-content>

package/support/package-meta.json

@@ -0,0 +1,103 @@
+{
+  "shortName": "network-status",
+  "package": {
+    "name": "@excom/network-status",
+    "version": "0.1.0",
+    "description": "<network-status> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "offline-banner": "<div>\n  <network-status></network-status>\n  <p role=\"alert\">You're offline — some features may be unavailable.</p>\n  <small role=\"note\">Banner is CSS-only, driven by\n    <code>[is-online]</code>. Go offline to see it appear.</small>\n</div>\n",
+    "simple": "<div>\n  <network-status></network-status>\n  <small role=\"note\">Live — reflects real connectivity. Toggle your\n    devtools network throttling (or your device's wifi/data) to see it change.</small>\n</div>\n"
+  },
+  "readme": "<h1 id=\"md-network-status\">network-status</h1>\n<p>Live connectivity readout — <code>navigator.onLine</code> plus connection type and\nspeed where the browser exposes them.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>CSS-driven UI</strong> Style from <code>[is-online]</code> / <code>[connection-type]</code></li>\n<li><strong>Live events</strong> <code>online</code> / <code>offline</code> / <code>change</code> fire as connectivity\nshifts — on transitions, never at mount</li>\n<li><strong>Bindable state</strong> <code>.provision</code> is the full snapshot; read it from Quark\nwith <code>prop(&quot;provision&quot;)</code></li>\n<li><strong>Network Information API</strong> Connection type + effective speed where\nsupported</li>\n<li><strong>Graceful degradation</strong> Unsupported fields stay <code>null</code>; core\nonline/offline still works everywhere</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Drop it anywhere and hook <code>[is-online]</code> / <code>[is-mounted]</code> with CSS, or\nlisten for its events from a parent.</p>\n<include-content data-language=\"html\"><template>&lt;network-status&gt;&lt;/network-status&gt;</template></include-content>\n<include-content data-language=\"css\"><template>network-status:not([is-mounted])::before {\n  content: \"Loading…\";\n}\nnetwork-status[is-online]::before {\n  content: \"📶 Online\";\n}\nnetwork-status[is-mounted]:not([is-online])::before {\n  content: \"📵 Offline\";\n}</template></include-content>\n<p>Nothing fires at mount: the first read sets <code>is-online</code> and <code>.provision</code>\nonly. React to the attribute (or <code>prop(&quot;provision&quot;)</code>) for the initial\nstate; <code>network-status-online</code> / <code>-offline</code> report transitions.</p>\n<p>The Network Information API (<code>connection-type</code>, <code>effective-type</code>,\n<code>downlink</code>, <code>rtt</code>) is Chromium-only — Safari and Firefox leave those\nfields <code>null</code>. Build critical UX on <code>is-online</code> alone; treat the rest as\na progressive enhancement. Safari/iOS also have known <code>navigator.onLine</code>\nreliability quirks — see <code>INTERNAL.md</code>.</p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-offline-banner\">Offline banner</h4>\n<p>A banner shown purely by CSS attribute selector — no listeners needed.</p>\n<p><include-content data-demo=\"offline-banner\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-network-status\">network-status</h1>\n<p>Live connectivity readout — <code>navigator.onLine</code> plus connection type and\nspeed where the browser exposes them.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>CSS-driven UI</strong> Style from <code>[is-online]</code> / <code>[connection-type]</code></li>\n<li><strong>Live events</strong> <code>online</code> / <code>offline</code> / <code>change</code> fire as connectivity\nshifts — on transitions, never at mount</li>\n<li><strong>Bindable state</strong> <code>.provision</code> is the full snapshot; read it from Quark\nwith <code>prop(&quot;provision&quot;)</code></li>\n<li><strong>Network Information API</strong> Connection type + effective speed where\nsupported</li>\n<li><strong>Graceful degradation</strong> Unsupported fields stay <code>null</code>; core\nonline/offline still works everywhere</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Drop it anywhere and hook <code>[is-online]</code> / <code>[is-mounted]</code> with CSS, or\nlisten for its events from a parent.</p>\n<include-content data-language=\"html\"><template>&lt;network-status&gt;&lt;/network-status&gt;</template></include-content>\n<include-content data-language=\"css\"><template>network-status:not([is-mounted])::before {\n  content: \"Loading…\";\n}\nnetwork-status[is-online]::before {\n  content: \"📶 Online\";\n}\nnetwork-status[is-mounted]:not([is-online])::before {\n  content: \"📵 Offline\";\n}</template></include-content>\n<p>Nothing fires at mount: the first read sets <code>is-online</code> and <code>.provision</code>\nonly. React to the attribute (or <code>prop(&quot;provision&quot;)</code>) for the initial\nstate; <code>network-status-online</code> / <code>-offline</code> report transitions.</p>\n<p>The Network Information API (<code>connection-type</code>, <code>effective-type</code>,\n<code>downlink</code>, <code>rtt</code>) is Chromium-only — Safari and Firefox leave those\nfields <code>null</code>. Build critical UX on <code>is-online</code> alone; treat the rest as\na progressive enhancement. Safari/iOS also have known <code>navigator.onLine</code>\nreliability quirks — see <code>INTERNAL.md</code>.</p>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-offline-banner\">Offline banner</h4>\n<p>A banner shown purely by CSS attribute selector — no listeners needed.</p>\n<p><include-content data-demo=\"offline-banner\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/network-status",
+    "shortName": "network-status",
+    "version": "0.1.0",
+    "description": "<network-status> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/network-status@0.1.0/dist/index.umd.min.js\"></script>",
+    "install": {
+      "npm": "npm install @excom/network-status"
+    },
+    "imports": {
+      "js": "import \"@excom/network-status\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/network-status\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/network-status\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "network-status",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "connection-type",
+          "type": "string",
+          "description": "Connection type (<code>wifi</code>, <code>cellular</code>, <code>ethernet</code>, …) from the Network Information API. <code>null</code> where unsupported (Safari, Firefox).",
+          "fieldName": "connectionType",
+          "surface": "state"
+        },
+        {
+          "name": "effective-type",
+          "type": "string",
+          "description": "Effective connection type (<code>4g</code>, <code>3g</code>, <code>2g</code>, <code>slow-2g</code>) from the Network Information API. <code>null</code> where unsupported (Safari, Firefox).",
+          "fieldName": "effectiveType",
+          "surface": "state"
+        },
+        {
+          "name": "is-online",
+          "type": "boolean",
+          "description": "Current <code>navigator.onLine</code> value.",
+          "fieldName": "isOnline",
+          "surface": "state"
+        }
+      ],
+      "events": [
+        {
+          "name": "network-status-change",
+          "description": "Dispatched when connection details change without an online/offline transition (Network Information API only), never at mount. <code>event.detail</code> is the full <code>.provision</code> payload.",
+          "type": "NetworkStatusChangeEvent",
+          "typeExpanded": "CustomEvent & { type: \"network-status-change\"; detail: { isOnline: boolean; connectionType?: string | null; effectiveType?: string | null; downlink?: number | null; rtt?: number | null; lastOnline?: number | null; lastOffline?: number | null; }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "network-status-offline",
+          "description": "Dispatched on a transition from online to offline, never at mount. <code>event.detail</code> is the full <code>.provision</code> payload.",
+          "type": "NetworkStatusOfflineEvent",
+          "typeExpanded": "CustomEvent & { type: \"network-status-offline\"; detail: { isOnline: boolean; connectionType?: string | null; effectiveType?: string | null; downlink?: number | null; rtt?: number | null; lastOnline?: number | null; lastOffline?: number | null; }; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "network-status-online",
+          "description": "Dispatched on a transition from offline to online, never at mount. <code>event.detail</code> is the full <code>.provision</code> payload.",
+          "type": "NetworkStatusOnlineEvent",
+          "typeExpanded": "CustomEvent & { type: \"network-status-online\"; detail: { isOnline: boolean; connectionType?: string | null; effectiveType?: string | null; downlink?: number | null; rtt?: number | null; lastOnline?: number | null; lastOffline?: number | null; }; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "NetworkStatusProvision",
+          "typeExpanded": "{ isOnline: boolean; connectionType?: string | null; effectiveType?: string | null; downlink?: number | null; rtt?: number | null; lastOnline?: number | null; lastOffline?: number | null; }",
+          "description": "Full connectivity snapshot: <code>{ isOnline, connectionType, effectiveType, downlink, rtt, lastOnline, lastOffline }</code>. Set at mount and on every change; the same object dispatched as <code>event.detail</code> on every fired event. <code>lastOnline</code> / <code>lastOffline</code> are stamped on transitions only. Not reflected as an attribute.",
+          "fieldName": "provision"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/network-status.test.ts

@@ -0,0 +1,401 @@
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import "../../index";
+
+const setOnLine = (value: boolean) =>
+  Object.defineProperty(navigator, "onLine", {
+    writable: true,
+    configurable: true,
+    value,
+  });
+
+const createConnection = (fields: Record<string, unknown> = {}) => {
+  const connection = new EventTarget();
+  Object.assign(connection, {
+    type: "wifi",
+    effectiveType: "4g",
+    downlink: 10,
+    rtt: 50,
+    ...fields,
+  });
+  return connection as EventTarget & Record<string, any>;
+};
+
+const mount = () =>
+  fixture<HTMLNetworkStatusElement>(`<network-status></network-status>`);
+
+describe("network-status", () => {
+  const originalConnection = Object.getOwnPropertyDescriptor(
+    navigator,
+    "connection",
+  );
+
+  const setConnection = (name: string, value: unknown) =>
+    Object.defineProperty(navigator, name, {
+      value,
+      writable: true,
+      configurable: true,
+    });
+
+  beforeAll(() => {
+    setOnLine(true);
+  });
+
+  beforeEach(() => {
+    setOnLine(true);
+    for (const name of ["connection", "mozConnection", "webkitConnection"]) {
+      setConnection(name, undefined);
+    }
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  afterAll(() => {
+    vi.clearAllMocks();
+    for (const name of ["connection", "mozConnection", "webkitConnection"]) {
+      delete (navigator as any)[name];
+    }
+    if (originalConnection) {
+      Object.defineProperty(navigator, "connection", originalConnection);
+    }
+  });
+
+  it("responds to online/offline/change events", () => {
+    const mockNetworkConnection = createConnection({ type: "cellular" });
+    setConnection("connection", mockNetworkConnection);
+
+    const networkStatus = mount();
+
+    expect(networkStatus).dom.to.equalTag(
+      `<network-status connection-type="cellular" effective-type="4g" is-mounted is-online></network-status>`,
+    );
+    expect(networkStatus.provision?.downlink).toBe(10);
+    expect(networkStatus.provision?.rtt).toBe(50);
+    // the first read is state, not a transition, no stamps yet
+    expect(networkStatus.provision?.lastOnline).toBeUndefined();
+    expect(networkStatus.provision?.lastOffline).toBeUndefined();
+
+    // Simulate going offline
+    setOnLine(false);
+    window.dispatchEvent(new Event("offline"));
+    expect(networkStatus).dom.to.equalTag(
+      `<network-status connection-type="cellular" effective-type="4g" is-mounted></network-status>`,
+    );
+    expect(networkStatus.provision?.downlink).toBe(10);
+    expect(networkStatus.provision?.rtt).toBe(50);
+    expect(networkStatus.provision?.lastOnline).toBeUndefined();
+    expect(networkStatus.provision?.lastOffline).toBeDefined();
+
+    // Simulate going online
+    setOnLine(true);
+    window.dispatchEvent(new Event("online"));
+    expect(networkStatus).dom.to.equalTag(
+      `<network-status connection-type="cellular" effective-type="4g" is-mounted is-online></network-status>`,
+    );
+    expect(networkStatus.provision?.downlink).toBe(10);
+    expect(networkStatus.provision?.rtt).toBe(50);
+    expect(networkStatus.provision?.lastOnline).toBeDefined();
+    expect(networkStatus.provision?.lastOffline).toBeDefined();
+
+    // Simulate network change
+    mockNetworkConnection.type = "wifi";
+    mockNetworkConnection.effectiveType = null;
+    mockNetworkConnection.downlink = 20;
+    mockNetworkConnection.rtt = 100;
+    mockNetworkConnection.dispatchEvent(new Event("change"));
+    expect(networkStatus).dom.to.equalTag(
+      `<network-status connection-type="wifi" is-mounted is-online></network-status>`,
+    );
+    expect(networkStatus.provision?.downlink).toBe(20);
+    expect(networkStatus.provision?.rtt).toBe(100);
+    expect(networkStatus.provision?.lastOnline).toBeDefined();
+    expect(networkStatus.provision?.lastOffline).toBeDefined();
+  });
+
+  describe("without the Network Information API", () => {
+    it("still reports online state and leaves connection fields unset", () => {
+      const el = mount();
+
+      expect(el).dom.to.equalTag(
+        `<network-status is-mounted is-online></network-status>`,
+      );
+      expect(el.provision).toEqual(
+        expect.objectContaining({
+          isOnline: true,
+          connectionType: undefined,
+          effectiveType: undefined,
+          downlink: undefined,
+          rtt: undefined,
+        }),
+      );
+      expect(el.provision?.lastOnline).toBeUndefined();
+      expect(el.provision?.lastOffline).toBeUndefined();
+    });
+
+    it("reports offline on connect when navigator.onLine is false", () => {
+      setOnLine(false);
+      const el = mount();
+
+      expect(el).dom.to.equalTag(
+        `<network-status is-mounted></network-status>`,
+      );
+      expect(el.provision?.isOnline).toBe(false);
+      expect(el.provision?.lastOnline).toBeUndefined();
+      expect(el.provision?.lastOffline).toBeUndefined();
+    });
+
+    it("does not emit at mount; emits network-status-online after offline → online", () => {
+      const el = document.createElement("network-status");
+      const online = vi.fn();
+      const offline = vi.fn();
+      const change = vi.fn();
+      const provisionSpy = vi.fn();
+      el.addEventListener("network-status-online", online);
+      el.addEventListener("network-status-offline", offline);
+      el.addEventListener("network-status-change", change);
+      el.addEventListener("neutron-provision", provisionSpy);
+
+      document.body.append(el);
+
+      // state is set, but the first read is not a transition
+      expect(el.hasAttribute("is-online")).toBe(true);
+      expect(el.provision?.isOnline).toBe(true);
+      expect(provisionSpy).toHaveBeenCalledTimes(1);
+      expect(online).not.toHaveBeenCalled();
+      expect(offline).not.toHaveBeenCalled();
+      expect(change).not.toHaveBeenCalled();
+
+      setOnLine(false);
+      window.dispatchEvent(new Event("offline"));
+      expect(offline).toHaveBeenCalledTimes(1);
+      expect(online).not.toHaveBeenCalled();
+
+      setOnLine(true);
+      window.dispatchEvent(new Event("online"));
+      expect(online).toHaveBeenCalledTimes(1);
+      expect(online.mock.calls[0][0].detail.isOnline).toBe(true);
+      expect(change).not.toHaveBeenCalled();
+    });
+
+    it("reports offline on connect without emitting, then emits network-status-online", () => {
+      setOnLine(false);
+      const el = document.createElement("network-status");
+      const online = vi.fn();
+      const offline = vi.fn();
+      el.addEventListener("network-status-online", online);
+      el.addEventListener("network-status-offline", offline);
+
+      document.body.append(el);
+      expect(el.hasAttribute("is-online")).toBe(false);
+      expect(offline).not.toHaveBeenCalled();
+
+      setOnLine(true);
+      window.dispatchEvent(new Event("online"));
+      expect(online).toHaveBeenCalledTimes(1);
+      expect(offline).not.toHaveBeenCalled();
+    });
+
+    it("transitions offline and online from window events", () => {
+      const el = mount();
+      const online = vi.fn();
+      const offline = vi.fn();
+      const change = vi.fn();
+      el.addEventListener("network-status-online", online);
+      el.addEventListener("network-status-offline", offline);
+      el.addEventListener("network-status-change", change);
+
+      setOnLine(false);
+      window.dispatchEvent(new Event("offline"));
+      expect(el.hasAttribute("is-online")).toBe(false);
+      expect(offline).toHaveBeenCalledTimes(1);
+      expect(offline.mock.calls[0][0].detail).toBe(el.provision);
+      expect(offline.mock.calls[0][0].detail.isOnline).toBe(false);
+
+      setOnLine(true);
+      window.dispatchEvent(new Event("online"));
+      expect(el.hasAttribute("is-online")).toBe(true);
+      expect(online).toHaveBeenCalledTimes(1);
+      expect(online.mock.calls[0][0].detail).toBe(el.provision);
+      expect(online.mock.calls[0][0].detail.isOnline).toBe(true);
+
+      expect(change).not.toHaveBeenCalled();
+    });
+
+    it("preserves lastOnline / lastOffline across transitions", () => {
+      vi.spyOn(Date, "now").mockReturnValue(1000);
+      const el = mount();
+      // mount is not a transition, so nothing is stamped
+      expect(el.provision?.lastOnline).toBeUndefined();
+
+      vi.spyOn(Date, "now").mockReturnValue(2000);
+      setOnLine(false);
+      window.dispatchEvent(new Event("offline"));
+      expect(el.provision?.lastOnline).toBeUndefined();
+      expect(el.provision?.lastOffline).toBe(2000);
+
+      vi.spyOn(Date, "now").mockReturnValue(3000);
+      setOnLine(true);
+      window.dispatchEvent(new Event("online"));
+      expect(el.provision?.lastOnline).toBe(3000);
+      expect(el.provision?.lastOffline).toBe(2000);
+    });
+
+    it("emits network-status-change when online fires without a transition", () => {
+      const el = mount();
+      const online = vi.fn();
+      const change = vi.fn();
+      el.addEventListener("network-status-online", online);
+      el.addEventListener("network-status-change", change);
+
+      // already online, a second `online` is not a transition
+      window.dispatchEvent(new Event("online"));
+
+      expect(online).not.toHaveBeenCalled();
+      expect(change).toHaveBeenCalledTimes(1);
+      expect(el.hasAttribute("is-online")).toBe(true);
+    });
+  });
+
+  describe("Network Information API", () => {
+    it("reads type / effectiveType / downlink / rtt from navigator.connection", () => {
+      setConnection(
+        "connection",
+        createConnection({ type: "ethernet", effectiveType: "4g", downlink: 100, rtt: 5 }),
+      );
+      const el = mount();
+
+      expect(el).dom.to.equalTag(
+        `<network-status connection-type="ethernet" effective-type="4g" is-mounted is-online></network-status>`,
+      );
+      expect(el.provision).toEqual(
+        expect.objectContaining({ downlink: 100, rtt: 5 }),
+      );
+    });
+
+    it("falls back to navigator.mozConnection", () => {
+      setConnection("mozConnection", createConnection({ type: "cellular" }));
+      const el = mount();
+      expect(el.connectionType).toBe("cellular");
+    });
+
+    it("falls back to navigator.webkitConnection", () => {
+      setConnection("webkitConnection", createConnection({ type: "bluetooth" }));
+      const el = mount();
+      expect(el.connectionType).toBe("bluetooth");
+    });
+
+    it("emits network-status-change (not online/offline) on a connection change", () => {
+      const connection = createConnection({ effectiveType: "4g" });
+      setConnection("connection", connection);
+      const el = mount();
+      const online = vi.fn();
+      const offline = vi.fn();
+      const change = vi.fn();
+      el.addEventListener("network-status-online", online);
+      el.addEventListener("network-status-offline", offline);
+      el.addEventListener("network-status-change", change);
+
+      connection.effectiveType = "slow-2g";
+      connection.dispatchEvent(new Event("change"));
+
+      expect(change).toHaveBeenCalledTimes(1);
+      expect(change.mock.calls[0][0].detail.effectiveType).toBe("slow-2g");
+      expect(el.effectiveType).toBe("slow-2g");
+      expect(online).not.toHaveBeenCalled();
+      expect(offline).not.toHaveBeenCalled();
+    });
+
+    it("subscribes to the connection's change event and unsubscribes on disconnect", async () => {
+      const connection = createConnection();
+      const addSpy = vi.spyOn(connection, "addEventListener");
+      const removeSpy = vi.spyOn(connection, "removeEventListener");
+      setConnection("connection", connection);
+
+      const el = mount();
+      expect(addSpy).toHaveBeenCalledWith("change", expect.any(Function));
+      const handler = addSpy.mock.calls[0][1];
+
+      el.remove();
+      await wait(0);
+
+      expect(removeSpy).toHaveBeenCalledWith("change", handler);
+      expect(el.networkConnection).toBe(null);
+    });
+  });
+
+  describe("lifecycle", () => {
+    it("removes window listeners on disconnect and stops updating", async () => {
+      const removeSpy = vi.spyOn(window, "removeEventListener");
+      const el = mount();
+
+      el.remove();
+      await wait(0);
+
+      expect(removeSpy).toHaveBeenCalledWith("online", expect.any(Function));
+      expect(removeSpy).toHaveBeenCalledWith("offline", expect.any(Function));
+
+      setOnLine(false);
+      window.dispatchEvent(new Event("offline"));
+      expect(el.isOnline).toBe(true);
+    });
+
+    it("keeps its listeners when moved synchronously within the document", async () => {
+      const connection = createConnection();
+      const connectionRemove = vi.spyOn(connection, "removeEventListener");
+      const connectionAdd = vi.spyOn(connection, "addEventListener");
+      setConnection("connection", connection);
+      const windowRemove = vi.spyOn(window, "removeEventListener");
+
+      const el = mount();
+      const parent = el.parentElement!;
+      expect(connectionAdd).toHaveBeenCalledTimes(1);
+
+      el.remove();
+      parent.append(el);
+      await wait(0);
+
+      expect(windowRemove).not.toHaveBeenCalledWith(
+        "online",
+        expect.any(Function),
+      );
+      expect(connectionRemove).not.toHaveBeenCalled();
+      // not re-subscribed either
+      expect(connectionAdd).toHaveBeenCalledTimes(1);
+      expect(el.networkConnection).toBe(connection);
+
+      // still live after the move
+      setOnLine(false);
+      window.dispatchEvent(new Event("offline"));
+      expect(el.hasAttribute("is-online")).toBe(false);
+    });
+
+    it("re-subscribes when reconnected after a real disconnect", async () => {
+      const addSpy = vi.spyOn(window, "addEventListener");
+      const el = mount();
+      const onlineAdds = () =>
+        addSpy.mock.calls.filter(([type]) => type === "online").length;
+      expect(onlineAdds()).toBe(1);
+
+      el.remove();
+      await wait(0);
+      document.body.append(el);
+      await wait(0);
+
+      expect(onlineAdds()).toBe(2);
+      expect(el.hasAttribute("is-online")).toBe(true);
+    });
+  });
+});

package/support/tests/offline-banner.view.test.ts

@@ -0,0 +1,20 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("offline-banner view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("renders the offline banner markup next to network-status", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "offline-banner"));
+    expect(root.querySelector("network-status")).toBeTruthy();
+    expect(root.querySelector("[role='alert']")?.textContent).toMatch(/offline/i);
+  });
+});

package/support/tests/simple.view.test.ts

@@ -0,0 +1,22 @@
+import "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  it,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+import { mountView, readDemo } from "@excom/quark/support/tests/view-helpers";
+
+describe("simple view", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("reflects online status", async () => {
+    const { root } = await mountView(readDemo(import.meta.url, "simple"));
+    const el = root.querySelector("network-status")!;
+    expect(el.hasAttribute("is-online") || el.hasAttribute("is-offline")).toBe(
+      true,
+    );
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@excom/heft-rig/profiles/default/config/tsconfig.json",
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}