@excom/service-worker 0.1.0

package/support/docs/README.md

@@ -0,0 +1,55 @@
+# service-worker
+
+Observes `navigator.serviceWorker` and optionally relays its events — zero app JS required.
+
+<include-content data-demo="simple"></include-content>
+
+## Features
+
+- **Observation only** Reports on an existing Service Worker; never registers one
+- **Support detection** `is-supported` reflects API availability
+- **Ready state** `is-ready` reflects once an active worker controls the page
+- **Event relay** `relay-events` forwards `message` / `messageerror` / `controllerchange` as plain DOM events
+- **Bindable state** `.provision` is `{ isSupported, isReady, hasController, scope }` — kept current on connect, `ready`, and every `controllerchange`; read it from Quark with `prop("provision")`
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+This element only *observes* an already-registered Service Worker — it does not call `navigator.serviceWorker.register(...)` itself. Register your Service Worker separately (in app code, or your build tool), then drop this element anywhere to expose its state as attributes and, optionally, relay its events.
+
+```html
+<service-worker relay-events></service-worker>
+<event-handler listen-for="message" fire-event="sw-message-received">
+  ...
+</event-handler>
+```
+
+Relayed events (`message`, `messageerror`, `controllerchange`) are dispatched with their original names — they are **not** prefixed with `service-worker-`.
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Support / mount / ready state
+
+`is-supported`, `is-mounted` (reflected by default), and `is-ready` are all plain attributes — style or branch on them with CSS. `is-ready` needs an app-registered Service Worker to ever resolve, so it will likely stay unset in this docs site.
+
+<include-content data-demo="simple"></include-content>
+
+#### Relay messages from your Service Worker
+
+Relaying `message` / `messageerror` / `controllerchange` requires a Service Worker that your app has already registered and that is actively posting messages — this is not runnable in this docs site, but works like so once wired up:
+
+```html
+<service-worker relay-events="message"></service-worker>
+<script>
+  document
+    .querySelector("service-worker")
+    .addEventListener("message", (e) => console.log(e.detail));
+</script>
+```

package/support/package-meta.json

@@ -0,0 +1,104 @@
+{
+  "shortName": "service-worker",
+  "package": {
+    "name": "@excom/service-worker",
+    "version": "0.1.0",
+    "description": "<service-worker> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "simple": "<div>\n  <service-worker></service-worker>\n</div>\n"
+  },
+  "readme": "<h1 id=\"md-service-worker\">service-worker</h1>\n<p>Observes <code>navigator.serviceWorker</code> and optionally relays its events — zero app JS required.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Observation only</strong> Reports on an existing Service Worker; never registers one</li>\n<li><strong>Support detection</strong> <code>is-supported</code> reflects API availability</li>\n<li><strong>Ready state</strong> <code>is-ready</code> reflects once an active worker controls the page</li>\n<li><strong>Event relay</strong> <code>relay-events</code> forwards <code>message</code> / <code>messageerror</code> / <code>controllerchange</code> as plain DOM events</li>\n<li><strong>Bindable state</strong> <code>.provision</code> is <code>{ isSupported, isReady, hasController, scope }</code> — kept current on connect, <code>ready</code>, and every <code>controllerchange</code>; read it from Quark with <code>prop(&quot;provision&quot;)</code></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>This element only <em>observes</em> an already-registered Service Worker — it does not call <code>navigator.serviceWorker.register(...)</code> itself. Register your Service Worker separately (in app code, or your build tool), then drop this element anywhere to expose its state as attributes and, optionally, relay its events.</p>\n<include-content data-language=\"html\"><template>&lt;service-worker relay-events&gt;&lt;/service-worker&gt;\n&lt;event-handler listen-for=\"message\" fire-event=\"sw-message-received\"&gt;\n  ...\n&lt;/event-handler&gt;</template></include-content>\n<p>Relayed events (<code>message</code>, <code>messageerror</code>, <code>controllerchange</code>) are dispatched with their original names — they are <strong>not</strong> prefixed with <code>service-worker-</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-support-mount-ready-state\">Support / mount / ready state</h4>\n<p><code>is-supported</code>, <code>is-mounted</code> (reflected by default), and <code>is-ready</code> are all plain attributes — style or branch on them with CSS. <code>is-ready</code> needs an app-registered Service Worker to ever resolve, so it will likely stay unset in this docs site.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h4 id=\"md-relay-messages-from-your-service-worker\">Relay messages from your Service Worker</h4>\n<p>Relaying <code>message</code> / <code>messageerror</code> / <code>controllerchange</code> requires a Service Worker that your app has already registered and that is actively posting messages — this is not runnable in this docs site, but works like so once wired up:</p>\n<include-content data-language=\"html\"><template>&lt;service-worker relay-events=\"message\"&gt;&lt;/service-worker&gt;\n&lt;script&gt;\n  document\n    .querySelector(\"service-worker\")\n    .addEventListener(\"message\", (e) =&gt; console.log(e.detail));\n&lt;/script&gt;</template></include-content>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-service-worker\">service-worker</h1>\n<p>Observes <code>navigator.serviceWorker</code> and optionally relays its events — zero app JS required.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Observation only</strong> Reports on an existing Service Worker; never registers one</li>\n<li><strong>Support detection</strong> <code>is-supported</code> reflects API availability</li>\n<li><strong>Ready state</strong> <code>is-ready</code> reflects once an active worker controls the page</li>\n<li><strong>Event relay</strong> <code>relay-events</code> forwards <code>message</code> / <code>messageerror</code> / <code>controllerchange</code> as plain DOM events</li>\n<li><strong>Bindable state</strong> <code>.provision</code> is <code>{ isSupported, isReady, hasController, scope }</code> — kept current on connect, <code>ready</code>, and every <code>controllerchange</code>; read it from Quark with <code>prop(&quot;provision&quot;)</code></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>This element only <em>observes</em> an already-registered Service Worker — it does not call <code>navigator.serviceWorker.register(...)</code> itself. Register your Service Worker separately (in app code, or your build tool), then drop this element anywhere to expose its state as attributes and, optionally, relay its events.</p>\n<include-content data-language=\"html\"><template>&lt;service-worker relay-events&gt;&lt;/service-worker&gt;\n&lt;event-handler listen-for=\"message\" fire-event=\"sw-message-received\"&gt;\n  ...\n&lt;/event-handler&gt;</template></include-content>\n<p>Relayed events (<code>message</code>, <code>messageerror</code>, <code>controllerchange</code>) are dispatched with their original names — they are <strong>not</strong> prefixed with <code>service-worker-</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-support-mount-ready-state\">Support / mount / ready state</h4>\n<p><code>is-supported</code>, <code>is-mounted</code> (reflected by default), and <code>is-ready</code> are all plain attributes — style or branch on them with CSS. <code>is-ready</code> needs an app-registered Service Worker to ever resolve, so it will likely stay unset in this docs site.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h4 id=\"md-relay-messages-from-your-service-worker\">Relay messages from your Service Worker</h4>\n<p>Relaying <code>message</code> / <code>messageerror</code> / <code>controllerchange</code> requires a Service Worker that your app has already registered and that is actively posting messages — this is not runnable in this docs site, but works like so once wired up:</p>\n<include-content data-language=\"html\"><template>&lt;service-worker relay-events=\"message\"&gt;&lt;/service-worker&gt;\n&lt;script&gt;\n  document\n    .querySelector(\"service-worker\")\n    .addEventListener(\"message\", (e) =&gt; console.log(e.detail));\n&lt;/script&gt;</template></include-content>\n"
+  },
+  "installation": {
+    "name": "@excom/service-worker",
+    "shortName": "service-worker",
+    "version": "0.1.0",
+    "description": "<service-worker> 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/service-worker@0.1.0/dist/index.umd.min.js\"></script>",
+    "install": {
+      "npm": "npm install @excom/service-worker"
+    },
+    "imports": {
+      "js": "import \"@excom/service-worker\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/service-worker\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/service-worker\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "service-worker",
+      "summary": "Observes <code>navigator.serviceWorker</code> — does not register a SW.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "relay-events",
+          "type": "tokenlist",
+          "description": "Space-separated <code>navigator.serviceWorker</code> events to relay onto this element. Bare attribute (no value) relays all three. Event names are relayed as-is — not prefixed with the tag.",
+          "fieldName": "relayEvents",
+          "surface": "option",
+          "values": "\"message\" | \"messageerror\" | \"controllerchange\""
+        },
+        {
+          "name": "is-ready",
+          "type": "boolean",
+          "description": "<code>navigator.serviceWorker.ready</code> has resolved — an active worker is controlling the page.",
+          "fieldName": "isReady",
+          "surface": "state"
+        },
+        {
+          "name": "is-supported",
+          "type": "boolean",
+          "description": "The Service Worker API is available (<code>&#39;serviceWorker&#39; in navigator</code>).",
+          "fieldName": "isSupported",
+          "surface": "state"
+        }
+      ],
+      "events": [
+        {
+          "name": "controllerchange",
+          "description": "Relayed verbatim from <code>navigator.serviceWorker</code>&#39;s <code>controllerchange</code> event when <code>controllerchange</code> is included in <code>relay-events</code>. Not tag-prefixed.",
+          "type": "ServiceWorkerControllerChangeEvent",
+          "typeExpanded": "CustomEvent & { type: \"controllerchange\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "message",
+          "description": "Relayed verbatim from <code>navigator.serviceWorker</code>&#39;s <code>message</code> event when <code>message</code> is included in <code>relay-events</code>. Not tag-prefixed. <code>event.detail</code> is <code>event.data</code> from the original message.",
+          "type": "ServiceWorkerMessageEvent",
+          "typeExpanded": "CustomEvent & { type: \"message\"; detail: unknown; bubbles: true; cancelable: true; composed: true }"
+        },
+        {
+          "name": "messageerror",
+          "description": "Relayed verbatim from <code>navigator.serviceWorker</code>&#39;s <code>messageerror</code> event when <code>messageerror</code> is included in <code>relay-events</code>. Not tag-prefixed.",
+          "type": "ServiceWorkerMessageErrorEvent",
+          "typeExpanded": "CustomEvent & { type: \"messageerror\"; detail: unknown; bubbles: true; cancelable: true; composed: true }"
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "ServiceWorkerProvision",
+          "typeExpanded": "{ isSupported: boolean; isReady: boolean; hasController: boolean; scope: string | null; }",
+          "description": "<code>{ isSupported, isReady, hasController, scope }</code> — set on connect, when <code>ready</code> resolves (<code>scope</code> comes from the registration), and on every <code>controllerchange</code>. Not reflected as an attribute.",
+          "fieldName": "provision"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}