@excom/network-status 0.1.0

package/.rush/temp/chunked-rush-logs/network-status.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/chunked-rush-logs/network-status.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/network-status.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 38.15602999999987
+}

package/.rush/temp/operation/build_docs/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 50.17207899999994
+}

package/.rush/temp/operation/build_package-metas/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 109.18563200000017
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/network-status": "../../packages/network-status:YAC8G8l1nkKknuTXH370JI0/DynCPkP81MNQcvbO6fA=:"
+}

package/config/rig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}

package/index.ts

@@ -0,0 +1,17 @@
+import { NetworkStatus } from "./network-status";
+
+NetworkStatus.define();
+
+export { NetworkStatus };
+
+type T_HTMLNetworkStatusElement = typeof NetworkStatus.CustomElement;
+declare global {
+  interface HTMLNetworkStatusElement extends T_HTMLNetworkStatusElement {}
+  interface Window {
+    HTMLNetworkStatusElement: HTMLNetworkStatusElement;
+  }
+  interface HTMLElementTagNameMap {
+    "network-status": HTMLNetworkStatusElement;
+  }
+}
+export type { HTMLNetworkStatusElement };

package/network-status.ts

@@ -0,0 +1,215 @@
+import { ConstructorType, Neutron, TEvent } from "@excom/neutron";
+
+interface NetworkConnection {
+  readonly type?: string;
+  readonly effectiveType?: string;
+  readonly downlink?: number;
+  readonly rtt?: number;
+  addEventListener(type: string, listener: EventListener): void;
+  removeEventListener(type: string, listener: EventListener): void;
+}
+
+declare global {
+  interface Navigator {
+    readonly connection?: NetworkConnection;
+    readonly mozConnection?: NetworkConnection;
+    readonly webkitConnection?: NetworkConnection;
+  }
+}
+
+export interface NetworkStatusProvision {
+  isOnline: boolean;
+  connectionType?: string | null;
+  effectiveType?: string | null;
+  downlink?: number | null;
+  rtt?: number | null;
+  lastOnline?: number | null;
+  lastOffline?: number | null;
+}
+
+export type NetworkStatusOnlineEvent = TEvent & {
+  type: "network-status-online";
+  detail: NetworkStatusProvision;
+};
+
+export type NetworkStatusOfflineEvent = TEvent & {
+  type: "network-status-offline";
+  detail: NetworkStatusProvision;
+};
+
+export type NetworkStatusChangeEvent = TEvent & {
+  type: "network-status-change";
+  detail: NetworkStatusProvision;
+};
+
+/**
+ * Reports live network connectivity — `navigator.onLine` plus, where the
+ * Network Information API is available, connection type and effective
+ * speed. Reflects `is-mounted` so CSS can distinguish "not yet upgraded"
+ * from a genuine offline state.
+ *
+ * The Network Information API (`connection-type` / `effective-type` /
+ * `downlink` / `rtt`) is Chromium-only — unsupported in Safari and
+ * Firefox, where those fields stay `null` and only `is-online` /
+ * `network-status-online` / `network-status-offline` are meaningful. See
+ * `INTERNAL.md` for known `navigator.onLine` reliability caveats.
+ *
+ * Nothing fires at mount — the first read only sets `is-online` and
+ * `.provision`. Select on the attribute / read the provision for the
+ * initial state; the events report transitions.
+ *
+ * @fires network-status-online - Dispatched on a transition from offline
+ *   to online, never at mount. `event.detail` is the full `.provision`
+ *   payload.
+ * @type NetworkStatusOnlineEvent
+ * @fires network-status-offline - Dispatched on a transition from online
+ *   to offline, never at mount. `event.detail` is the full `.provision`
+ *   payload.
+ * @type NetworkStatusOfflineEvent
+ * @fires network-status-change - Dispatched when connection details
+ *   change without an online/offline transition (Network Information API
+ *   only), never at mount. `event.detail` is the full `.provision`
+ *   payload.
+ * @type NetworkStatusChangeEvent
+ */
+export const NetworkStatus = Neutron({
+  tag: "network-status",
+  reflectDefaultProps: ["isMounted"],
+  props: {
+    // state
+    /**
+     * @provision
+     * Full connectivity snapshot: `{ isOnline, connectionType,
+     * effectiveType, downlink, rtt, lastOnline, lastOffline }`. Set at
+     * mount and on every change; the same object dispatched as
+     * `event.detail` on every fired event. `lastOnline` / `lastOffline`
+     * are stamped on transitions only. Not reflected as an attribute.
+     * @type NetworkStatusProvision
+     */
+    provision: Object as unknown as ConstructorType<NetworkStatusProvision>,
+    /**
+     * @state
+     * Current `navigator.onLine` value.
+     */
+    isOnline: Boolean,
+    /**
+     * @state
+     * Connection type (`wifi`, `cellular`, `ethernet`, …) from the
+     * Network Information API. `null` where unsupported (Safari,
+     * Firefox).
+     */
+    connectionType: String,
+    /**
+     * @state
+     * Effective connection type (`4g`, `3g`, `2g`, `slow-2g`) from the
+     * Network Information API. `null` where unsupported (Safari,
+     * Firefox).
+     */
+    effectiveType: String,
+    // private
+    networkConnection: Object as unknown as ConstructorType<NetworkConnection>,
+  },
+})
+  .defineMethods({
+    setNetworkData: (
+      { isOnline, networkConnection, provision },
+      argData: { isOnline?: boolean } | undefined = {}
+    ) => {
+      const _isOnline = argData.isOnline ?? isOnline;
+      /* `provision` is only set here, so its absence is the first read.
+         A Boolean prop reads `false` before it's set, so `isOnline` alone
+         can't tell "unset" from "offline". */
+      const isFirstRead = !provision;
+      const isOnlineChanged = !isFirstRead && isOnline !== _isOnline;
+      const _connectionType = networkConnection?.type;
+      const _effectiveType = networkConnection?.effectiveType;
+      const newData = {
+        isOnline: _isOnline,
+        connectionType: _connectionType,
+        effectiveType: _effectiveType,
+        downlink: networkConnection?.downlink,
+        rtt: networkConnection?.rtt,
+        lastOnline:
+          isOnlineChanged && _isOnline ? Date.now() : provision?.lastOnline,
+        lastOffline:
+          isOnlineChanged && !_isOnline ? Date.now() : provision?.lastOffline,
+      };
+      return {
+        isOnline: _isOnline,
+        connectionType: _connectionType,
+        effectiveType: _effectiveType,
+        provision: newData as NetworkStatusProvision,
+        /* First read is state, not a transition: nothing fires at mount.
+           After that: `online` / `offline` on a flip, `change` otherwise. */
+        ...(isFirstRead
+          ? {}
+          : {
+              emit: [
+                `network-status-${
+                  isOnlineChanged
+                    ? _isOnline
+                      ? "online"
+                      : "offline"
+                    : "change"
+                }`,
+                { detail: newData },
+              ],
+            }),
+      };
+    },
+    handleOnline: () => ({
+      setNetworkData: [{ isOnline: true }],
+    }),
+    handleOffline: () => ({
+      setNetworkData: [{ isOnline: false }],
+    }),
+    handleChange: () => ({
+      setNetworkData: [],
+    }),
+  })
+  .onConnected(({ isMoving, handleOnline, handleOffline, handleChange }) => {
+    // A move: keep the existing listeners
+    if (isMoving) return;
+
+    // Window + connection listeners
+    window.addEventListener("online", handleOnline);
+    window.addEventListener("offline", handleOffline);
+
+    // Initial `networkConnection`
+    const networkConnection =
+      navigator.connection ||
+      navigator.mozConnection ||
+      navigator.webkitConnection;
+
+    networkConnection?.addEventListener("change", handleChange);
+
+    return [
+      { networkConnection },
+      {
+        setNetworkData: [
+          {
+            isOnline: navigator.onLine,
+          },
+        ],
+      },
+    ];
+  })
+  .onDisconnected(
+    ({
+      isMoving,
+      handleOnline,
+      handleOffline,
+      handleChange,
+      networkConnection,
+    }) => {
+      // A move: keep the existing listeners
+      if (isMoving) return;
+      // Drop window + connection listeners
+      window.removeEventListener("online", handleOnline);
+      window.removeEventListener("offline", handleOffline);
+      networkConnection?.removeEventListener("change", handleChange);
+      return {
+        networkConnection: null,
+      };
+    }
+  );

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@excom/network-status",
+  "version": "0.1.0",
+  "description": "<network-status> custom element",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/neutron": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/network-status"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/network-status/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "network-status",
+    "neutron",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "kit-element"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/rush-logs/network-status.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/network-status.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/rush-logs/network-status.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/network-status.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/network-status.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/network-status.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/support/custom-elements.json

@@ -0,0 +1,156 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "network-status.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "NetworkStatus",
+          "customElement": true,
+          "tagName": "network-status",
+          "description": "Reports live network connectivity — `navigator.onLine` plus, where the Network Information API is available, connection type and effective speed. Reflects `is-mounted` so CSS can distinguish \"not yet upgraded\" from a genuine offline state. The Network Information API (`connection-type` / `effective-type` / `downlink` / `rtt`) is Chromium-only — unsupported in Safari and Firefox, where those fields stay `null` and only `is-online` / `network-status-online` / `network-status-offline` are meaningful. See `INTERNAL.md` for known `navigator.onLine` reliability caveats. Nothing fires at mount — the first read only sets `is-online` and `.provision`. Select on the attribute / read the provision for the initial state; the events report transitions.",
+          "attributes": [
+            {
+              "name": "is-online",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Current `navigator.onLine` value.",
+              "fieldName": "isOnline"
+            },
+            {
+              "name": "connection-type",
+              "type": {
+                "text": "string"
+              },
+              "description": "Connection type (`wifi`, `cellular`, `ethernet`, …) from the Network Information API. `null` where unsupported (Safari, Firefox).",
+              "fieldName": "connectionType"
+            },
+            {
+              "name": "effective-type",
+              "type": {
+                "text": "string"
+              },
+              "description": "Effective connection type (`4g`, `3g`, `2g`, `slow-2g`) from the Network Information API. `null` where unsupported (Safari, Firefox).",
+              "fieldName": "effectiveType"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "provision",
+              "type": {
+                "text": "NetworkStatusProvision",
+                "expanded": "{ isOnline: boolean; connectionType?: string | null; effectiveType?: string | null; downlink?: number | null; rtt?: number | null; lastOnline?: number | null; lastOffline?: number | null; }"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Full connectivity snapshot: `{ isOnline, connectionType, effectiveType, downlink, rtt, lastOnline, lastOffline }`. Set at mount and on every change; the same object dispatched as `event.detail` on every fired event. `lastOnline` / `lastOffline` are stamped on transitions only. Not reflected as an attribute.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isOnline",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Current `navigator.onLine` value.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "connectionType",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Connection type (`wifi`, `cellular`, `ethernet`, …) from the Network Information API. `null` where unsupported (Safari, Firefox).",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "effectiveType",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Effective connection type (`4g`, `3g`, `2g`, `slow-2g`) from the Network Information API. `null` where unsupported (Safari, Firefox).",
+              "_neutron": {
+                "surface": "state"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "network-status-online",
+              "description": "Dispatched on a transition from offline to online, never at mount. `event.detail` is the full `.provision` payload.",
+              "type": {
+                "text": "NetworkStatusOnlineEvent",
+                "expanded": "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 }"
+              }
+            },
+            {
+              "name": "network-status-offline",
+              "description": "Dispatched on a transition from online to offline, never at mount. `event.detail` is the full `.provision` payload.",
+              "type": {
+                "text": "NetworkStatusOfflineEvent",
+                "expanded": "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-change",
+              "description": "Dispatched when connection details change without an online/offline transition (Network Information API only), never at mount. `event.detail` is the full `.provision` payload.",
+              "type": {
+                "text": "NetworkStatusChangeEvent",
+                "expanded": "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 }"
+              }
+            }
+          ],
+          "_neutron": {
+            "provisions": [
+              {
+                "name": "provision",
+                "type": {
+                  "text": "NetworkStatusProvision",
+                  "expanded": "{ isOnline: boolean; connectionType?: string | null; effectiveType?: string | null; downlink?: number | null; rtt?: number | null; lastOnline?: number | null; lastOffline?: number | null; }"
+                },
+                "description": "Full connectivity snapshot: `{ isOnline, connectionType, effectiveType, downlink, rtt, lastOnline, lastOffline }`. Set at mount and on every change; the same object dispatched as `event.detail` on every fired event. `lastOnline` / `lastOffline` are stamped on transitions only. Not reflected as an attribute.",
+                "fieldName": "provision"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "NetworkStatus",
+          "declaration": {
+            "name": "NetworkStatus",
+            "module": "network-status.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "network-status",
+          "declaration": {
+            "name": "NetworkStatus",
+            "module": "network-status.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/offline-banner.html

@@ -0,0 +1,6 @@
+<div>
+  <network-status></network-status>
+  <p role="alert">You're offline — some features may be unavailable.</p>
+  <small role="note">Banner is CSS-only, driven by
+    <code>[is-online]</code>. Go offline to see it appear.</small>
+</div>

package/support/demos/simple.html

@@ -0,0 +1,5 @@
+<div>
+  <network-status></network-status>
+  <small role="note">Live — reflects real connectivity. Toggle your
+    devtools network throttling (or your device's wifi/data) to see it change.</small>
+</div>

package/support/dist-docs/network-status.md

@@ -0,0 +1,125 @@
+# network-status
+
+Live connectivity readout — `navigator.onLine` plus connection type and
+speed where the browser exposes them.
+
+
+```html
+<div>
+  <network-status></network-status>
+  <small role="note">Live — reflects real connectivity. Toggle your
+    devtools network throttling (or your device's wifi/data) to see it change.</small>
+</div>
+```
+
+
+## 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
+
+
+`@excom/network-status` v0.1.0
+
+```bash
+pnpm add @excom/network-status
+```
+
+```bash
+npm install @excom/network-status
+```
+
+```bash
+yarn add @excom/network-status
+```
+
+### Import
+
+```ts
+import "@excom/network-status";
+```
+
+
+
+## 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
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `is-online` | state | `boolean` |  |  | Current `navigator.onLine` value. |
+| `connection-type` | state | `string` |  |  | Connection type (`wifi`, `cellular`, `ethernet`, …) from the Network Information API. `null` where unsupported (Safari, Firefox). |
+| `effective-type` | state | `string` |  |  | Effective connection type (`4g`, `3g`, `2g`, `slow-2g`) from the Network Information API. `null` where unsupported (Safari, Firefox). |
+
+#### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `NetworkStatusProvision` (`{ isOnline: boolean; connectionType?: string \| null; effectiveType?: string \| null; downlink?: number \| null; rtt?: number \| null; lastOnline?: number \| null; lastOffline?: number \| null; }`) | Full connectivity snapshot: `{ isOnline, connectionType, effectiveType, downlink, rtt, lastOnline, lastOffline }`. Set at mount and on every change; the same object dispatched as `event.detail` on every fired event. `lastOnline` / `lastOffline` are stamped on transitions only. Not reflected as an attribute. |
+
+#### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `network-status-online` | `NetworkStatusOnlineEvent` (`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 }`) | Dispatched on a transition from offline to online, never at mount. `event.detail` is the full `.provision` payload. |
+| `network-status-offline` | `NetworkStatusOfflineEvent` (`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 }`) | Dispatched on a transition from online to offline, never at mount. `event.detail` is the full `.provision` payload. |
+| `network-status-change` | `NetworkStatusChangeEvent` (`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 }`) | Dispatched when connection details change without an online/offline transition (Network Information API only), never at mount. `event.detail` is the full `.provision` payload. |
+
+
+
+### Examples
+
+#### Offline banner
+
+A banner shown purely by CSS attribute selector — no listeners needed.
+
+
+```html
+<div>
+  <network-status></network-status>
+  <p role="alert">You're offline — some features may be unavailable.</p>
+  <small role="note">Banner is CSS-only, driven by
+    <code>[is-online]</code>. Go offline to see it appear.</small>
+</div>
+```

package/support/docs/INTERNAL.md

@@ -0,0 +1,12 @@
+- `navigator.onLine` is not a reliable "can reach the internet" signal.
+  Findings from the ws investigation: iOS Safari (and other WebKit
+  embeds) can report `true` while on a captive portal or a cellular
+  connection with no actual data path, and some Android WebViews lag
+  behind the real link state by several seconds after a transition.
+  Treat `is-online` as "the OS thinks it has a link", not as an
+  end-to-end connectivity check — pair with an actual request/heartbeat
+  if you need the stronger guarantee.
+- Network Information API (`connection-type` / `effective-type` /
+  `downlink` / `rtt`) is Chromium-only. Safari and Firefox never expose
+  `navigator.connection`, so those fields stay `null` indefinitely on
+  those browsers — this is expected, not a bug.