@excom/provider-geolocation 0.1.0

package/support/dist-docs/provider-geolocation.md

@@ -0,0 +1,108 @@
+# provider-geolocation
+
+Declarative Geolocation API — request a position, read the result from
+attributes/state.
+
+
+```html
+<div id="geo-request-demo">
+  <button type="button" command="--request" commandfor="geo-request">
+    Request my location
+  </button>
+  <provider-geolocation id="geo-request" is-paused></provider-geolocation>
+  <output>Click above — your browser will prompt for permission.</output>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    #geo-request-demo { @on neutron-provision (handle: setOutputFromElementData); }
+  </quark-sheet>
+</div>
+```
+
+
+## Features
+
+- **Attribute-driven** Request + read a position through attributes
+- **User-gesture requests** `is-paused` + the `--request` command
+  so permission prompts follow a click
+- **One-shot or watch** `watch-position` streams updates instead of a
+  single read
+
+## Installation
+
+
+`@excom/provider-geolocation` v0.1.0
+
+```bash
+pnpm add @excom/provider-geolocation
+```
+
+```bash
+npm install @excom/provider-geolocation
+```
+
+```bash
+yarn add @excom/provider-geolocation
+```
+
+### Import
+
+```ts
+import "@excom/provider-geolocation";
+```
+
+
+
+## Usage
+
+Requesting location on page load is poor UX (an unsolicited permission
+prompt) — gate it behind a user gesture with `is-paused` and a trigger:
+
+```html
+<button type="button" command="--request" commandfor="geo">
+  Share my location
+</button>
+<provider-geolocation id="geo" is-paused></provider-geolocation>
+```
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `is-paused` | option | `boolean` |  |  | Skip making a request on connect. `provider-geolocation-request` still works while paused. |
+| `high-accuracy` | option | `boolean` |  |  | Request the most accurate position available (more battery / time cost). |
+| `geo-timeout` | option | `number` | `"Infinity"` |  | Give up and fire `provider-geolocation-error` after this many ms. |
+| `maximum-age` | option | `number` |  |  | Accept a cached position up to this many ms old instead of requesting a fresh one. Ignored when `watch-position` is set (always `0`, i.e. no caching). |
+| `watch-position` | option | `boolean` |  |  | Keep requesting — `provider-geolocation-success` fires on every position update instead of once. Uses `navigator.geolocation.watchPosition` under the hood. |
+| `is-requesting` | state | `boolean` |  |  | A position request is currently pending. |
+| `is-success` | state | `boolean` |  |  | The most recent request resolved successfully. With `watch-position`, stays set across updates. |
+| `is-error` | state | `boolean` |  |  | The most recent request failed. Fires with the `error` event. |
+
+#### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `GeoSuccess` (`{ coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }`) | Latest result: the coords object on success, or the `GeolocationPositionError` (or thrown error) on failure. Not reflected as an attribute. |
+
+#### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provider-geolocation-success` | `ProviderGeolocationSuccessEvent` (`CustomEvent & { type: "provider-geolocation-success"; detail: { coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched on every successful position read (including each update while `watch-position` is set). |
+| `provider-geolocation-error` | `ProviderGeolocationErrorEvent` (`CustomEvent & { type: "provider-geolocation-error"; detail: GeolocationPositionError; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request fails (permission denied, timeout, position unavailable, or a thrown error). |
+
+#### Commands
+
+| Command | Action |
+| --- | --- |
+| `--request` | (Re)requests the position on demand — the standard way to request from a button (`<button command="--request" commandfor="…">`) while `is-paused` is set, or to force a fresh read at any time. |
+
+#### Default actions
+
+| Event | Default behavior (unless preventDefault() is called) |
+| --- | --- |
+| `provider-geolocation-success` | Stores the result in `provision` and sets `is-success` (clearing `is-requesting` / `is-error`). |
+| `provider-geolocation-error` | Stores the error in `provision` and sets `is-error` (clearing `is-requesting` / `is-success`). |

package/support/docs/README.md

@@ -0,0 +1,34 @@
+# provider-geolocation
+
+Declarative Geolocation API — request a position, read the result from
+attributes/state.
+
+<include-content data-demo="request"></include-content>
+
+## Features
+
+- **Attribute-driven** Request + read a position through attributes
+- **User-gesture requests** `is-paused` + the `--request` command
+  so permission prompts follow a click
+- **One-shot or watch** `watch-position` streams updates instead of a
+  single read
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Requesting location on page load is poor UX (an unsolicited permission
+prompt) — gate it behind a user gesture with `is-paused` and a trigger:
+
+```html
+<button type="button" command="--request" commandfor="geo">
+  Share my location
+</button>
+<provider-geolocation id="geo" is-paused></provider-geolocation>
+```
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>

package/support/package-meta.json

@@ -0,0 +1,148 @@
+{
+  "shortName": "provider-geolocation",
+  "package": {
+    "name": "@excom/provider-geolocation",
+    "version": "0.1.0",
+    "description": "<provider-geolocation> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "request": "<div id=\"geo-request-demo\">\n  <button type=\"button\" command=\"--request\" commandfor=\"geo-request\">\n    Request my location\n  </button>\n  <provider-geolocation id=\"geo-request\" is-paused></provider-geolocation>\n  <output>Click above — your browser will prompt for permission.</output>\n  <quark-sheet>\n    @use \"/demo-utils\" as *;\n\n    #geo-request-demo { @on neutron-provision (handle: setOutputFromElementData); }\n  </quark-sheet>\n</div>\n"
+  },
+  "readme": "<h1 id=\"md-provider-geolocation\">provider-geolocation</h1>\n<p>Declarative Geolocation API — request a position, read the result from\nattributes/state.</p>\n<p><include-content data-demo=\"request\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Attribute-driven</strong> Request + read a position through attributes</li>\n<li><strong>User-gesture requests</strong> <code>is-paused</code> + the <code>--request</code> command\nso permission prompts follow a click</li>\n<li><strong>One-shot or watch</strong> <code>watch-position</code> streams updates instead of a\nsingle read</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>Requesting location on page load is poor UX (an unsolicited permission\nprompt) — gate it behind a user gesture with <code>is-paused</code> and a trigger:</p>\n<include-content data-language=\"html\"><template>&lt;button type=\"button\" command=\"--request\" commandfor=\"geo\"&gt;\n  Share my location\n&lt;/button&gt;\n&lt;provider-geolocation id=\"geo\" is-paused&gt;&lt;/provider-geolocation&gt;</template></include-content>\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",
+  "docs": {
+    "readme": "<h1 id=\"md-provider-geolocation\">provider-geolocation</h1>\n<p>Declarative Geolocation API — request a position, read the result from\nattributes/state.</p>\n<p><include-content data-demo=\"request\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Attribute-driven</strong> Request + read a position through attributes</li>\n<li><strong>User-gesture requests</strong> <code>is-paused</code> + the <code>--request</code> command\nso permission prompts follow a click</li>\n<li><strong>One-shot or watch</strong> <code>watch-position</code> streams updates instead of a\nsingle read</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>Requesting location on page load is poor UX (an unsolicited permission\nprompt) — gate it behind a user gesture with <code>is-paused</code> and a trigger:</p>\n<include-content data-language=\"html\"><template>&lt;button type=\"button\" command=\"--request\" commandfor=\"geo\"&gt;\n  Share my location\n&lt;/button&gt;\n&lt;provider-geolocation id=\"geo\" is-paused&gt;&lt;/provider-geolocation&gt;</template></include-content>\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"
+  },
+  "installation": {
+    "name": "@excom/provider-geolocation",
+    "shortName": "provider-geolocation",
+    "version": "0.1.0",
+    "description": "<provider-geolocation> 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/provider-geolocation@0.1.0/dist/index.umd.min.js\"></script>",
+    "install": {
+      "npm": "npm install @excom/provider-geolocation"
+    },
+    "imports": {
+      "js": "import \"@excom/provider-geolocation\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/provider-geolocation\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/provider-geolocation\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "provider-geolocation",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "geo-timeout",
+          "type": "number",
+          "description": "Give up and fire <code>provider-geolocation-error</code> after this many ms.",
+          "fieldName": "geoTimeout",
+          "surface": "option",
+          "default": "\"Infinity\""
+        },
+        {
+          "name": "high-accuracy",
+          "type": "boolean",
+          "description": "Request the most accurate position available (more battery / time cost).",
+          "fieldName": "highAccuracy",
+          "surface": "option"
+        },
+        {
+          "name": "is-paused",
+          "type": "boolean",
+          "description": "Skip making a request on connect. <code>provider-geolocation-request</code> still works while paused.",
+          "fieldName": "isPaused",
+          "surface": "option"
+        },
+        {
+          "name": "maximum-age",
+          "type": "number",
+          "description": "Accept a cached position up to this many ms old instead of requesting a fresh one. Ignored when <code>watch-position</code> is set (always <code>0</code>, i.e. no caching).",
+          "fieldName": "maximumAge",
+          "surface": "option"
+        },
+        {
+          "name": "watch-position",
+          "type": "boolean",
+          "description": "Keep requesting — <code>provider-geolocation-success</code> fires on every position update instead of once. Uses <code>navigator.geolocation.watchPosition</code> under the hood.",
+          "fieldName": "watchPosition",
+          "surface": "option"
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "The most recent request failed. Fires with the <code>error</code> event.",
+          "fieldName": "isError",
+          "surface": "state"
+        },
+        {
+          "name": "is-requesting",
+          "type": "boolean",
+          "description": "A position request is currently pending.",
+          "fieldName": "isRequesting",
+          "surface": "state"
+        },
+        {
+          "name": "is-success",
+          "type": "boolean",
+          "description": "The most recent request resolved successfully. With <code>watch-position</code>, stays set across updates.",
+          "fieldName": "isSuccess",
+          "surface": "state"
+        }
+      ],
+      "events": [
+        {
+          "name": "provider-geolocation-error",
+          "description": "Dispatched when the request fails (permission denied, timeout, position unavailable, or a thrown error).",
+          "type": "ProviderGeolocationErrorEvent",
+          "typeExpanded": "CustomEvent & { type: \"provider-geolocation-error\"; detail: GeolocationPositionError; bubbles: true; cancelable: true; composed: true }",
+          "defaultAction": "Stores the error in <code>provision</code> and sets <code>is-error</code> (clearing <code>is-requesting</code> / <code>is-success</code>)."
+        },
+        {
+          "name": "provider-geolocation-success",
+          "description": "Dispatched on every successful position read (including each update while <code>watch-position</code> is set).",
+          "type": "ProviderGeolocationSuccessEvent",
+          "typeExpanded": "CustomEvent & { type: \"provider-geolocation-success\"; detail: { coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }; bubbles: true; cancelable: true; composed: true }",
+          "defaultAction": "Stores the result in <code>provision</code> and sets <code>is-success</code> (clearing <code>is-requesting</code> / <code>is-error</code>)."
+        }
+      ],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [
+        {
+          "name": "--request",
+          "description": "(Re)requests the position on demand — the standard way to request from a button (<code>&lt;button command=&quot;--request&quot; commandfor=&quot;…&quot;&gt;</code>) while <code>is-paused</code> is set, or to force a fresh read at any time."
+        }
+      ],
+      "defaultActions": [
+        {
+          "name": "provider-geolocation-error",
+          "description": "Stores the error in <code>provision</code> and sets <code>is-error</code> (clearing <code>is-requesting</code> / <code>is-success</code>)."
+        },
+        {
+          "name": "provider-geolocation-success",
+          "description": "Stores the result in <code>provision</code> and sets <code>is-success</code> (clearing <code>is-requesting</code> / <code>is-error</code>)."
+        }
+      ],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "GeoSuccess",
+          "typeExpanded": "{ coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }",
+          "description": "Latest result: the coords object on success, or the <code>GeolocationPositionError</code> (or thrown error) on failure. Not reflected as an attribute.",
+          "fieldName": "provision"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}