@excom/provider-orientation 0.1.0

package/.rush/temp/chunked-rush-logs/provider-orientation.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-orientation.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-orientation.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": 37.539288999999826
+}

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

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

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

@@ -0,0 +1,3 @@
+{
+  "../../packages/provider-orientation": "../../packages/provider-orientation: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 { ProviderOrientation } from "./provider-orientation";
+
+ProviderOrientation.define();
+
+export { ProviderOrientation };
+
+type T_HTMLProviderOrientationElement =
+  typeof ProviderOrientation.CustomElement;
+declare global {
+  interface HTMLProviderOrientationElement extends T_HTMLProviderOrientationElement {}
+  interface Window {
+    HTMLProviderOrientationElement: HTMLProviderOrientationElement;
+  }
+  interface HTMLElementTagNameMap {
+    "provider-orientation": HTMLProviderOrientationElement;
+  }
+}
+export type { HTMLProviderOrientationElement };

package/package.json

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

@@ -0,0 +1,225 @@
+import { ConstructorType, Neutron, TEvent } from "@excom/neutron";
+
+export type ProviderOrientationSuccess = {
+  bearing: number;
+  alpha: number | null;
+};
+
+export type ProviderOrientationError = string | Error;
+
+export type ProviderOrientationSuccessEvent = TEvent & {
+  type: "provider-orientation-success";
+  detail: ProviderOrientationSuccess;
+};
+
+export type ProviderOrientationErrorEvent = TEvent & {
+  type: "provider-orientation-error";
+  detail: ProviderOrientationError;
+};
+
+/**
+ * Wraps the device orientation / compass APIs — request a heading and
+ * read updates from attributes/state, no app JS required. Requests on
+ * connect unless `is-paused`, same as the other `provider-*` elements —
+ * but on iOS that request must happen synchronously inside a user
+ * gesture (`DeviceOrientationEvent.requestPermission()`), so a
+ * connect-time request will silently fail there. **Set `is-paused` and
+ * invoke the `--request` command from a button instead** unless you know
+ * your app only targets Android/desktop (the handler runs in a microtask
+ * of the click, inside its user activation).
+ *
+ * Bearing (`provision.bearing`) is normalized to degrees clockwise from
+ * magnetic north (`0`–`360`) across both the iOS
+ * (`webkitCompassHeading`) and Android/absolute (`alpha`) code paths, so
+ * consumers don't need to branch on platform.
+ *
+ * Lifecycle: the `window` listener is tracked by Neutron — removed when
+ * the element leaves the document, restored (and the request repeated
+ * unless `is-paused`) when it is reconnected, and kept across a DOM move.
+ * Removing the element while an iOS permission prompt is still open
+ * abandons that request: nothing is attached when it settles, and a
+ * later reconnect requests again.
+ *
+ * @fires provider-orientation-success - Dispatched on every compass
+ *   update (throttled by `compass-throttle-ms`). `bearing` is
+ *   normalized 0-360°; `alpha` is the raw
+ *   `DeviceOrientationEvent.alpha` where available.
+ * @type ProviderOrientationSuccessEvent
+ * @fires provider-orientation-error - Dispatched when the permission
+ *   request is denied, or fails for any other reason.
+ * @type ProviderOrientationErrorEvent
+ * @command --request - Requests permission (iOS) and starts listening for
+ *   orientation updates. Invoke it from a button (`<button
+ *   command="--request" commandfor="…">`) so the user activation is there.
+ * @default-action provider-orientation-success - Stores `{ bearing,
+ *   alpha }` in `provision` and sets `is-success` (clearing `is-requesting` /
+ *   `is-error`).
+ * @default-action provider-orientation-error - Stores the error in
+ *   `provision` and sets `is-error` (clearing `is-requesting` /
+ *   `is-success`).
+ */
+export const ProviderOrientation = Neutron({
+  tag: "provider-orientation",
+  props: {
+    // options
+    /**
+     * @option
+     * Skip requesting on connect. On iOS this is effectively required
+     * (a connect-time request happens outside a user gesture and will
+     * be denied) — pair with `provider-orientation-request` from a
+     * click handler instead (see class docs).
+     */
+    isPaused: Boolean,
+    /**
+     * @option
+     * Minimum ms between `provider-orientation-success` updates.
+     * Android can fire `deviceorientationabsolute` at 60-200 Hz;
+     * without throttling that floods listeners and CSS/Quark bindings.
+     * @default 100
+     */
+    compassThrottleMs: {
+      type: Number,
+      defaultValue: () => 100,
+    },
+    // state
+    /**
+     * @state
+     * iOS only: the permission request is pending (between
+     * `provider-orientation-request` and the user's response).
+     */
+    isRequesting: Boolean,
+    /**
+     * @state
+     * Listening for orientation updates (permission granted where
+     * required). Stays set across updates.
+     */
+    isSuccess: Boolean,
+    /**
+     * @state
+     * The permission request was denied, or listening failed to start.
+     */
+    isError: Boolean,
+    /**
+     * @provision
+     * Latest reading: `{ bearing, alpha }` on success, or the error on
+     * failure. Not reflected as an attribute.
+     * @type ProviderOrientationSuccess
+     */
+    provision: Object as unknown as ConstructorType<any>,
+    // private
+    permissionPromise: Promise as unknown as ConstructorType<
+      Promise<PermissionStatus>
+    >,
+    lastCompassUpdate: {
+      type: Number,
+      defaultValue: () => 0,
+    },
+  },
+})
+  .defineMethods({
+    handleSuccess: (_, { bearing, alpha }) => ({
+      // Emit success event for continuous updates
+      emit: ["provider-orientation-success", { detail: { bearing, alpha } }],
+    }),
+    handleError: (_, error) => ({
+      emit: ["provider-orientation-error", { detail: error }],
+    }),
+    makeRequest: () => {
+      const DOE =
+        typeof DeviceOrientationEvent !== "undefined"
+          ? (DeviceOrientationEvent as any)
+          : null;
+      if (DOE && typeof DOE.requestPermission === "function") {
+        // iOS: request permission (async) from a user-gesture context
+        return {
+          permissionPromise: DOE.requestPermission(),
+          isRequesting: true,
+        };
+      }
+      /* Android / desktop: no permission here. Attach synchronously so it
+         stays in the user-gesture context; some Android browser / PWA
+         combos silently block `deviceorientation` outside a gesture. */
+      return {
+        _attachCompassListener: [],
+        isRequesting: false,
+        isSuccess: true,
+        isError: false,
+      };
+    },
+    /**
+     * Register the `window` orientation listener once, via Neutron's
+     * tracked registry (`target: window`). Dropped on disconnect,
+     * restored on reconnect, never added twice.
+     */
+    // @ts-ignore TODO fix defineMethods sibling references
+    _attachCompassListener: ({ compassHandler }) => ({
+      addListener: [
+        "ondeviceorientationabsolute" in window
+          ? "deviceorientationabsolute"
+          : "deviceorientation",
+        compassHandler,
+        { capture: true, target: window },
+      ],
+    }),
+    compassHandler: ({ compassThrottleMs, lastCompassUpdate }, e: any) => {
+      // Throttle: Android fires `deviceorientationabsolute` at 60-200 Hz
+      const now = Date.now();
+      if (now - lastCompassUpdate < compassThrottleMs) return;
+
+      let bearing: number | null = null;
+
+      // iOS: `webkitCompassHeading` (degrees from magnetic north, 0-360)
+      if (typeof e.webkitCompassHeading === "number") {
+        bearing = e.webkitCompassHeading;
+      } else if (typeof e.alpha === "number" && e.absolute) {
+        // Android / absolute: `alpha` is degrees from north
+        bearing = (360 - e.alpha) % 360;
+      }
+
+      if (bearing !== null) {
+        return {
+          lastCompassUpdate: now,
+          handleSuccess: [{ bearing, alpha: e.alpha ?? undefined }],
+        };
+      }
+    },
+  })
+  .onConnected(
+    // A DOM move keeps the listener (Neutron restores it). Only a fresh
+    // connect or a real reconnect requests again.
+    ({ isPaused, isMoving }) =>
+      !isPaused &&
+      !isMoving && {
+        makeRequest: [],
+      }
+  )
+  .onPropUnset("isPaused", () => ({
+    makeRequest: [],
+  }))
+  .onPromiseResolved("permissionPromise", (element, result) => {
+    /* Removed while the permission prompt was open: no disconnect will
+       clean up, so attach nothing. A later reconnect requests again via
+       `onConnected`. */
+    if (!element.isConnected) return;
+    // @ts-ignore TODO fix onPromiseResolved types
+    if (result?.permissionPromise === "granted") {
+      return { _attachCompassListener: [] };
+    }
+    return { handleError: ["Device orientation permission denied"] };
+  })
+  .onPromiseRejected("permissionPromise", (_, err) => ({
+    handleError: [err],
+  }))
+  .onCommand("--request", () => ({ makeRequest: [] }))
+  .onEventDefault("provider-orientation-success", (_, { detail }) => ({
+    provision: detail,
+    isRequesting: false,
+    isSuccess: true,
+    isError: false,
+  }))
+  .onEventDefault("provider-orientation-error", (_, { detail }) => ({
+    provision: detail,
+    isRequesting: false,
+    isSuccess: false,
+    isError: true,
+  }));

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

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

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

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

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

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

package/rush-logs/provider-orientation.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-orientation.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,208 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "provider-orientation.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "ProviderOrientation",
+          "customElement": true,
+          "tagName": "provider-orientation",
+          "description": "Wraps the device orientation / compass APIs — request a heading and read updates from attributes/state, no app JS required. Requests on connect unless `is-paused`, same as the other `provider-*` elements — but on iOS that request must happen synchronously inside a user gesture (`DeviceOrientationEvent.requestPermission()`), so a connect-time request will silently fail there. **Set `is-paused` and invoke the `--request` command from a button instead** unless you know your app only targets Android/desktop (the handler runs in a microtask of the click, inside its user activation). Bearing (`provision.bearing`) is normalized to degrees clockwise from magnetic north (`0`–`360`) across both the iOS (`webkitCompassHeading`) and Android/absolute (`alpha`) code paths, so consumers don't need to branch on platform. Lifecycle: the `window` listener is tracked by Neutron — removed when the element leaves the document, restored (and the request repeated unless `is-paused`) when it is reconnected, and kept across a DOM move. Removing the element while an iOS permission prompt is still open abandons that request: nothing is attached when it settles, and a later reconnect requests again.",
+          "attributes": [
+            {
+              "name": "is-paused",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Skip requesting on connect. On iOS this is effectively required (a connect-time request happens outside a user gesture and will be denied) — pair with `provider-orientation-request` from a click handler instead (see class docs).",
+              "fieldName": "isPaused"
+            },
+            {
+              "name": "compass-throttle-ms",
+              "type": {
+                "text": "number"
+              },
+              "description": "Minimum ms between `provider-orientation-success` updates. Android can fire `deviceorientationabsolute` at 60-200 Hz; without throttling that floods listeners and CSS/Quark bindings.",
+              "fieldName": "compassThrottleMs",
+              "default": 100
+            },
+            {
+              "name": "is-requesting",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "iOS only: the permission request is pending (between `provider-orientation-request` and the user's response).",
+              "fieldName": "isRequesting"
+            },
+            {
+              "name": "is-success",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Listening for orientation updates (permission granted where required). Stays set across updates.",
+              "fieldName": "isSuccess"
+            },
+            {
+              "name": "is-error",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "The permission request was denied, or listening failed to start.",
+              "fieldName": "isError"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "isPaused",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Skip requesting on connect. On iOS this is effectively required (a connect-time request happens outside a user gesture and will be denied) — pair with `provider-orientation-request` from a click handler instead (see class docs).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "compassThrottleMs",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Minimum ms between `provider-orientation-success` updates. Android can fire `deviceorientationabsolute` at 60-200 Hz; without throttling that floods listeners and CSS/Quark bindings.",
+              "default": 100,
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isRequesting",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "iOS only: the permission request is pending (between `provider-orientation-request` and the user's response).",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isSuccess",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Listening for orientation updates (permission granted where required). Stays set across updates.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isError",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "The permission request was denied, or listening failed to start.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "provision",
+              "type": {
+                "text": "ProviderOrientationSuccess",
+                "expanded": "{ bearing: number; alpha: number | null; }"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Latest reading: `{ bearing, alpha }` on success, or the error on failure. Not reflected as an attribute.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "provider-orientation-success",
+              "description": "Dispatched on every compass update (throttled by `compass-throttle-ms`). `bearing` is normalized 0-360°; `alpha` is the raw `DeviceOrientationEvent.alpha` where available.",
+              "type": {
+                "text": "ProviderOrientationSuccessEvent",
+                "expanded": "CustomEvent & { type: \"provider-orientation-success\"; detail: { bearing: number; alpha: number | null; }; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "provider-orientation-error",
+              "description": "Dispatched when the permission request is denied, or fails for any other reason.",
+              "type": {
+                "text": "ProviderOrientationErrorEvent",
+                "expanded": "CustomEvent & { type: \"provider-orientation-error\"; detail: string | Error; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "provisions": [
+              {
+                "name": "provision",
+                "type": {
+                  "text": "ProviderOrientationSuccess",
+                  "expanded": "{ bearing: number; alpha: number | null; }"
+                },
+                "description": "Latest reading: `{ bearing, alpha }` on success, or the error on failure. Not reflected as an attribute.",
+                "fieldName": "provision"
+              }
+            ],
+            "commands": [
+              {
+                "name": "--request",
+                "description": "Requests permission (iOS) and starts listening for orientation updates. Invoke it from a button (`<button command=\"--request\" commandfor=\"…\">`) so the user activation is there."
+              }
+            ],
+            "defaultActions": [
+              {
+                "name": "provider-orientation-success",
+                "description": "Stores `{ bearing, alpha }` in `provision` and sets `is-success` (clearing `is-requesting` / `is-error`)."
+              },
+              {
+                "name": "provider-orientation-error",
+                "description": "Stores the error in `provision` and sets `is-error` (clearing `is-requesting` / `is-success`)."
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "ProviderOrientation",
+          "declaration": {
+            "name": "ProviderOrientation",
+            "module": "provider-orientation.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "provider-orientation",
+          "declaration": {
+            "name": "ProviderOrientation",
+            "module": "provider-orientation.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/request.html

@@ -0,0 +1,14 @@
+<div id="orient-demo">
+  <button type="button" command="--request" commandfor="orient">
+    Enable compass
+  </button>
+  <provider-orientation id="orient" is-paused></provider-orientation>
+  <p class="status">No reading yet — click above. Requires a device
+    sensor (desktop browsers usually have none).</p>
+  <output>Waiting…</output>
+  <quark-sheet>
+    @use "/demo-utils" as *;
+
+    #orient-demo { @on neutron-provision (handle: setOutputFromElementData); }
+  </quark-sheet>
+</div>