@excom/provider-geolocation 0.1.0

package/.rush/temp/chunked-rush-logs/provider-geolocation.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/provider-geolocation.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/provider-geolocation.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.29784399999994
+}

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": 41.80963500000007
+}

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": 113.07771000000002
+}

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

@@ -0,0 +1,3 @@
+{
+  "../../packages/provider-geolocation": "../../packages/provider-geolocation: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,18 @@
+import { ProviderGeolocation } from "./provider-geolocation";
+
+ProviderGeolocation.define();
+
+export { ProviderGeolocation };
+
+type T_HTMLProviderGeolocationElement =
+  typeof ProviderGeolocation.CustomElement;
+declare global {
+  interface HTMLProviderGeolocationElement extends T_HTMLProviderGeolocationElement {}
+  interface Window {
+    HTMLProviderGeolocationElement: HTMLProviderGeolocationElement;
+  }
+  interface HTMLElementTagNameMap {
+    "provider-geolocation": HTMLProviderGeolocationElement;
+  }
+}
+export type { HTMLProviderGeolocationElement };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@excom/provider-geolocation",
+  "version": "0.1.0",
+  "description": "<provider-geolocation> 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/provider-geolocation"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/provider-geolocation/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "provider-geolocation",
+    "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/provider-geolocation.ts

@@ -0,0 +1,222 @@
+import { ConstructorType, Neutron, TEvent } from "@excom/neutron";
+
+export type GeoSuccess = {
+  coords: {
+    longitude: number;
+    latitude: number;
+    altitude?: number;
+    accuracy?: number;
+    altitudeAccuracy?: number;
+    heading?: number;
+    speed?: number;
+    timestamp?: number;
+  };
+};
+
+export type ProviderGeolocationSuccessEvent = TEvent & {
+  type: "provider-geolocation-success";
+  detail: GeoSuccess;
+};
+
+export type ProviderGeolocationErrorEvent = TEvent & {
+  type: "provider-geolocation-error";
+  detail: GeolocationPositionError;
+};
+
+/**
+ * Wraps the Geolocation API as a declarative element — request the
+ * user's position (once or continuously) and read the result from
+ * attributes/state.
+ *
+ * Lifecycle: a `watch-position` watch is cleared when the element leaves
+ * the document and started again on reconnect (unless `is-paused`); a
+ * DOM move keeps the current watch / request. A one-shot request that
+ * settles after the element was removed is dropped — no event, no state.
+ *
+ * @fires provider-geolocation-success - Dispatched on every successful
+ *   position read (including each update while `watch-position` is
+ *   set).
+ * @type ProviderGeolocationSuccessEvent
+ * @fires provider-geolocation-error - Dispatched when the request fails
+ *   (permission denied, timeout, position unavailable, or a thrown
+ *   error).
+ * @type ProviderGeolocationErrorEvent
+ * @command --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-action provider-geolocation-success - Stores the result in
+ *   `provision` and sets `is-success` (clearing `is-requesting` /
+ *   `is-error`).
+ * @default-action provider-geolocation-error - Stores the error in
+ *   `provision` and sets `is-error` (clearing `is-requesting` /
+ *   `is-success`).
+ */
+export const ProviderGeolocation = Neutron({
+  tag: "provider-geolocation",
+  props: {
+    // options
+    /**
+     * @option
+     * Skip making a request on connect. `provider-geolocation-request`
+     * still works while paused.
+     */
+    isPaused: Boolean,
+    /**
+     * @option
+     * Request the most accurate position available (more battery /
+     * time cost).
+     */
+    highAccuracy: Boolean,
+    /**
+     * @option
+     * Give up and fire `provider-geolocation-error` after this many ms.
+     * @default Infinity
+     */
+    geoTimeout: {
+      type: Number,
+      defaultValue: () => Infinity,
+    },
+    /**
+     * @option
+     * 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).
+     */
+    maximumAge: Number,
+    /**
+     * @option
+     * Keep requesting — `provider-geolocation-success` fires on every
+     * position update instead of once. Uses
+     * `navigator.geolocation.watchPosition` under the hood.
+     */
+    watchPosition: Boolean,
+    // state
+    /**
+     * @state
+     * A position request is currently pending.
+     */
+    isRequesting: Boolean,
+    /**
+     * @state
+     * The most recent request resolved successfully. With
+     * `watch-position`, stays set across updates.
+     */
+    isSuccess: Boolean,
+    /**
+     * @state
+     * The most recent request failed. Fires with the `error` event.
+     */
+    isError: Boolean,
+    /**
+     * @provision
+     * Latest result: the coords object on success, or the
+     * `GeolocationPositionError` (or thrown error) on failure.
+     * Not reflected as an attribute.
+     * @type GeoSuccess
+     */
+    provision: Object as unknown as ConstructorType<
+      GeoSuccess | GeolocationPositionError | Error
+    >,
+    // private
+    existingWatchId: {
+      type: Number,
+      attr: false,
+    },
+  },
+})
+  .defineMethods({
+    handlePosition: (element, location: GeolocationPosition) => {
+      // Settled after disconnect: drop it, don't mutate a detached node.
+      if (!element.isConnected) return;
+      return {
+        // Success for a continuous watch update
+        emit: [
+          "provider-geolocation-success",
+          {
+            detail: {
+              coords: {
+                latitude: location.coords.latitude,
+                longitude: location.coords.longitude,
+                altitude: location.coords.altitude ?? undefined,
+                accuracy: location.coords.accuracy ?? undefined,
+                altitudeAccuracy: location.coords.altitudeAccuracy ?? undefined,
+                heading: location.coords.heading ?? undefined,
+                speed: location.coords.speed ?? undefined,
+                timestamp: location.timestamp,
+              },
+            },
+          },
+        ],
+      };
+    },
+    handleError: (element, error: GeolocationPositionError) => {
+      if (!element.isConnected) return;
+      return {
+        emit: ["provider-geolocation-error", { detail: error }],
+      };
+    },
+    makeRequest: ({
+      highAccuracy,
+      geoTimeout,
+      maximumAge,
+      watchPosition,
+      // @ts-ignore TODO defineMethods
+      handlePosition,
+      // @ts-ignore TODO defineMethods
+      handleError,
+    }) => {
+      let newWatchId: number | void | null = null;
+      try {
+        newWatchId = navigator.geolocation[
+          watchPosition ? "watchPosition" : "getCurrentPosition"
+        ](handlePosition, handleError, {
+          maximumAge: watchPosition ? 0 : (maximumAge ?? 60000),
+          timeout: geoTimeout,
+          enableHighAccuracy: highAccuracy ?? false,
+        });
+      } catch (e) {
+        handleError(e);
+      }
+      return {
+        existingWatchId: newWatchId ?? null,
+        isRequesting: true,
+      };
+    },
+  })
+  .onConnected(
+    // A DOM move keeps the current request / watch. Only a fresh connect
+    // or a real reconnect requests again.
+    ({ isPaused, isMoving }) =>
+      !isPaused &&
+      !isMoving && {
+        makeRequest: [],
+      }
+  )
+  .onPropUnset("isPaused", () => ({
+    makeRequest: [],
+  }))
+  .onPropChanged("existingWatchId", (_, previous) => {
+    if (typeof previous.existingWatchId === "number") {
+      navigator.geolocation.clearWatch(previous.existingWatchId);
+    }
+  })
+  .onCommand("--request", () => ({ makeRequest: [] }))
+  .onEventDefault("provider-geolocation-success", (_, { detail }) => ({
+    provision: detail,
+    isRequesting: false,
+    isSuccess: true,
+    isError: false,
+  }))
+  .onEventDefault("provider-geolocation-error", (_, { detail }) => ({
+    provision: detail,
+    isRequesting: false,
+    isSuccess: false,
+    isError: true,
+  }))
+  .onDisconnected(({ isMoving }) => {
+    if (isMoving) return;
+    return {
+      existingWatchId: null,
+    };
+  });

package/rush-logs/provider-geolocation.apply-exports.cache.log

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

package/rush-logs/provider-geolocation.apply-exports.log

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

package/rush-logs/provider-geolocation.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/provider-geolocation.build_docs.log

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

package/rush-logs/provider-geolocation.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/provider-geolocation.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,271 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "provider-geolocation.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ProviderGeolocation",
+          "customElement": true,
+          "tagName": "provider-geolocation",
+          "description": "Wraps the Geolocation API as a declarative element — request the user's position (once or continuously) and read the result from attributes/state. Lifecycle: a `watch-position` watch is cleared when the element leaves the document and started again on reconnect (unless `is-paused`); a DOM move keeps the current watch / request. A one-shot request that settles after the element was removed is dropped — no event, no state.",
+          "attributes": [
+            {
+              "name": "is-paused",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Skip making a request on connect. `provider-geolocation-request` still works while paused.",
+              "fieldName": "isPaused"
+            },
+            {
+              "name": "high-accuracy",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Request the most accurate position available (more battery / time cost).",
+              "fieldName": "highAccuracy"
+            },
+            {
+              "name": "geo-timeout",
+              "type": {
+                "text": "number"
+              },
+              "description": "Give up and fire `provider-geolocation-error` after this many ms.",
+              "fieldName": "geoTimeout",
+              "default": "Infinity"
+            },
+            {
+              "name": "maximum-age",
+              "type": {
+                "text": "number"
+              },
+              "description": "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).",
+              "fieldName": "maximumAge"
+            },
+            {
+              "name": "watch-position",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Keep requesting — `provider-geolocation-success` fires on every position update instead of once. Uses `navigator.geolocation.watchPosition` under the hood.",
+              "fieldName": "watchPosition"
+            },
+            {
+              "name": "is-requesting",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "A position request is currently pending.",
+              "fieldName": "isRequesting"
+            },
+            {
+              "name": "is-success",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "The most recent request resolved successfully. With `watch-position`, stays set across updates.",
+              "fieldName": "isSuccess"
+            },
+            {
+              "name": "is-error",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "The most recent request failed. Fires with the `error` event.",
+              "fieldName": "isError"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "isPaused",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Skip making a request on connect. `provider-geolocation-request` still works while paused.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "highAccuracy",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Request the most accurate position available (more battery / time cost).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "geoTimeout",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Give up and fire `provider-geolocation-error` after this many ms.",
+              "default": "Infinity",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "maximumAge",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "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).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "watchPosition",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Keep requesting — `provider-geolocation-success` fires on every position update instead of once. Uses `navigator.geolocation.watchPosition` under the hood.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isRequesting",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "A position request is currently pending.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isSuccess",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "The most recent request resolved successfully. With `watch-position`, stays set across updates.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isError",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "The most recent request failed. Fires with the `error` event.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "provision",
+              "type": {
+                "text": "GeoSuccess",
+                "expanded": "{ coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Latest result: the coords object on success, or the `GeolocationPositionError` (or thrown error) on failure. Not reflected as an attribute.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "provider-geolocation-success",
+              "description": "Dispatched on every successful position read (including each update while `watch-position` is set).",
+              "type": {
+                "text": "ProviderGeolocationSuccessEvent",
+                "expanded": "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 }"
+              }
+            },
+            {
+              "name": "provider-geolocation-error",
+              "description": "Dispatched when the request fails (permission denied, timeout, position unavailable, or a thrown error).",
+              "type": {
+                "text": "ProviderGeolocationErrorEvent",
+                "expanded": "CustomEvent & { type: \"provider-geolocation-error\"; detail: GeolocationPositionError; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "provisions": [
+              {
+                "name": "provision",
+                "type": {
+                  "text": "GeoSuccess",
+                  "expanded": "{ 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 `GeolocationPositionError` (or thrown error) on failure. Not reflected as an attribute.",
+                "fieldName": "provision"
+              }
+            ],
+            "commands": [
+              {
+                "name": "--request",
+                "description": "(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."
+              }
+            ],
+            "defaultActions": [
+              {
+                "name": "provider-geolocation-success",
+                "description": "Stores the result in `provision` and sets `is-success` (clearing `is-requesting` / `is-error`)."
+              },
+              {
+                "name": "provider-geolocation-error",
+                "description": "Stores the error in `provision` and sets `is-error` (clearing `is-requesting` / `is-success`)."
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ProviderGeolocation",
+          "declaration": {
+            "name": "ProviderGeolocation",
+            "module": "provider-geolocation.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "provider-geolocation",
+          "declaration": {
+            "name": "ProviderGeolocation",
+            "module": "provider-geolocation.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/request.html

@@ -0,0 +1,12 @@
+<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>