@excom/provider-orientation 0.1.0

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

@@ -0,0 +1,126 @@
+# provider-orientation
+
+Declarative device orientation / compass — request a heading, read the
+normalized bearing from attributes/state.
+
+## Features
+
+- **Attribute-driven** Request + read a compass heading through attributes
+- **Normalized bearing** `0`–`360°` from magnetic north on both iOS and
+  Android, one shape either way
+- **Throttled updates** `compass-throttle-ms` caps update frequency
+  (Android can fire 60-200 Hz)
+- **iOS-aware** Works with the required user-gesture permission flow
+
+## Installation
+
+
+`@excom/provider-orientation` v0.1.0
+
+```bash
+pnpm add @excom/provider-orientation
+```
+
+```bash
+npm install @excom/provider-orientation
+```
+
+```bash
+yarn add @excom/provider-orientation
+```
+
+### Import
+
+```ts
+import "@excom/provider-orientation";
+```
+
+
+
+## Usage
+
+**Requires a user gesture on iOS.** `DeviceOrientationEvent
+.requestPermission()` must run synchronously inside a click handler or
+Safari denies it — so set `is-paused` and invoke the `--request` command
+from a button rather than relying on the connect-time auto-request (the
+handler runs in a microtask of the click, inside its user activation):
+
+```html
+<button type="button" command="--request" commandfor="compass">
+  Enable compass
+</button>
+<provider-orientation id="compass" is-paused></provider-orientation>
+```
+
+```css
+compass-needle {
+  transform: rotate(calc(var(--bearing, 0) * 1deg));
+}
+```
+
+Android and desktop browsers with a sensor don't require permission and
+will start listening as soon as the request fires; browsers with no
+sensor at all simply never report a reading.
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `is-paused` | option | `boolean` |  |  | 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). |
+| `compass-throttle-ms` | option | `number` | `100` |  | Minimum ms between `provider-orientation-success` updates. Android can fire `deviceorientationabsolute` at 60-200 Hz; without throttling that floods listeners and CSS/Quark bindings. |
+| `is-requesting` | state | `boolean` |  |  | iOS only: the permission request is pending (between `provider-orientation-request` and the user's response). |
+| `is-success` | state | `boolean` |  |  | Listening for orientation updates (permission granted where required). Stays set across updates. |
+| `is-error` | state | `boolean` |  |  | The permission request was denied, or listening failed to start. |
+
+#### Provision
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provision` | `ProviderOrientationSuccess` (`{ bearing: number; alpha: number \| null; }`) | Latest reading: `{ bearing, alpha }` on success, or the error on failure. Not reflected as an attribute. |
+
+#### Fires
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `provider-orientation-success` | `ProviderOrientationSuccessEvent` (`CustomEvent & { type: "provider-orientation-success"; detail: { bearing: number; alpha: number \| null; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched on every compass update (throttled by `compass-throttle-ms`). `bearing` is normalized 0-360°; `alpha` is the raw `DeviceOrientationEvent.alpha` where available. |
+| `provider-orientation-error` | `ProviderOrientationErrorEvent` (`CustomEvent & { type: "provider-orientation-error"; detail: string \| Error; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the permission request is denied, or fails for any other reason. |
+
+#### Commands
+
+| Command | Action |
+| --- | --- |
+| `--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 actions
+
+| Event | Default behavior (unless preventDefault() is called) |
+| --- | --- |
+| `provider-orientation-success` | Stores `{ bearing, alpha }` in `provision` and sets `is-success` (clearing `is-requesting` / `is-error`). |
+| `provider-orientation-error` | Stores the error in `provision` and sets `is-error` (clearing `is-requesting` / `is-success`). |
+
+
+
+### Examples
+
+#### Request on click
+
+
+```html
+<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>
+```

package/support/docs/README.md

@@ -0,0 +1,52 @@
+# provider-orientation
+
+Declarative device orientation / compass — request a heading, read the
+normalized bearing from attributes/state.
+
+## Features
+
+- **Attribute-driven** Request + read a compass heading through attributes
+- **Normalized bearing** `0`–`360°` from magnetic north on both iOS and
+  Android, one shape either way
+- **Throttled updates** `compass-throttle-ms` caps update frequency
+  (Android can fire 60-200 Hz)
+- **iOS-aware** Works with the required user-gesture permission flow
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+**Requires a user gesture on iOS.** `DeviceOrientationEvent
+.requestPermission()` must run synchronously inside a click handler or
+Safari denies it — so set `is-paused` and invoke the `--request` command
+from a button rather than relying on the connect-time auto-request (the
+handler runs in a microtask of the click, inside its user activation):
+
+```html
+<button type="button" command="--request" commandfor="compass">
+  Enable compass
+</button>
+<provider-orientation id="compass" is-paused></provider-orientation>
+```
+
+```css
+compass-needle {
+  transform: rotate(calc(var(--bearing, 0) * 1deg));
+}
+```
+
+Android and desktop browsers with a sensor don't require permission and
+will start listening as soon as the request fires; browsers with no
+sensor at all simply never report a reading.
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Request on click
+
+<include-content data-demo="request"></include-content>

package/support/package-meta.json

@@ -0,0 +1,127 @@
+{
+  "shortName": "provider-orientation",
+  "package": {
+    "name": "@excom/provider-orientation",
+    "version": "0.1.0",
+    "description": "<provider-orientation> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "request": "<div id=\"orient-demo\">\n  <button type=\"button\" command=\"--request\" commandfor=\"orient\">\n    Enable compass\n  </button>\n  <provider-orientation id=\"orient\" is-paused></provider-orientation>\n  <p class=\"status\">No reading yet — click above. Requires a device\n    sensor (desktop browsers usually have none).</p>\n  <output>Waiting…</output>\n  <quark-sheet>\n    @use \"/demo-utils\" as *;\n\n    #orient-demo { @on neutron-provision (handle: setOutputFromElementData); }\n  </quark-sheet>\n</div>\n"
+  },
+  "readme": "<h1 id=\"md-provider-orientation\">provider-orientation</h1>\n<p>Declarative device orientation / compass — request a heading, read the\nnormalized bearing from attributes/state.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Attribute-driven</strong> Request + read a compass heading through attributes</li>\n<li><strong>Normalized bearing</strong> <code>0</code>–<code>360°</code> from magnetic north on both iOS and\nAndroid, one shape either way</li>\n<li><strong>Throttled updates</strong> <code>compass-throttle-ms</code> caps update frequency\n(Android can fire 60-200 Hz)</li>\n<li><strong>iOS-aware</strong> Works with the required user-gesture permission flow</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><strong>Requires a user gesture on iOS.</strong> <code>DeviceOrientationEvent .requestPermission()</code> must run synchronously inside a click handler or\nSafari denies it — so set <code>is-paused</code> and invoke the <code>--request</code> command\nfrom a button rather than relying on the connect-time auto-request (the\nhandler runs in a microtask of the click, inside its user activation):</p>\n<include-content data-language=\"html\"><template>&lt;button type=\"button\" command=\"--request\" commandfor=\"compass\"&gt;\n  Enable compass\n&lt;/button&gt;\n&lt;provider-orientation id=\"compass\" is-paused&gt;&lt;/provider-orientation&gt;</template></include-content>\n<include-content data-language=\"css\"><template>compass-needle {\n  transform: rotate(calc(var(--bearing, 0) * 1deg));\n}</template></include-content>\n<p>Android and desktop browsers with a sensor don&#39;t require permission and\nwill start listening as soon as the request fires; browsers with no\nsensor at all simply never report a reading.</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-request-on-click\">Request on click</h4>\n<p><include-content data-demo=\"request\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-provider-orientation\">provider-orientation</h1>\n<p>Declarative device orientation / compass — request a heading, read the\nnormalized bearing from attributes/state.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Attribute-driven</strong> Request + read a compass heading through attributes</li>\n<li><strong>Normalized bearing</strong> <code>0</code>–<code>360°</code> from magnetic north on both iOS and\nAndroid, one shape either way</li>\n<li><strong>Throttled updates</strong> <code>compass-throttle-ms</code> caps update frequency\n(Android can fire 60-200 Hz)</li>\n<li><strong>iOS-aware</strong> Works with the required user-gesture permission flow</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><strong>Requires a user gesture on iOS.</strong> <code>DeviceOrientationEvent .requestPermission()</code> must run synchronously inside a click handler or\nSafari denies it — so set <code>is-paused</code> and invoke the <code>--request</code> command\nfrom a button rather than relying on the connect-time auto-request (the\nhandler runs in a microtask of the click, inside its user activation):</p>\n<include-content data-language=\"html\"><template>&lt;button type=\"button\" command=\"--request\" commandfor=\"compass\"&gt;\n  Enable compass\n&lt;/button&gt;\n&lt;provider-orientation id=\"compass\" is-paused&gt;&lt;/provider-orientation&gt;</template></include-content>\n<include-content data-language=\"css\"><template>compass-needle {\n  transform: rotate(calc(var(--bearing, 0) * 1deg));\n}</template></include-content>\n<p>Android and desktop browsers with a sensor don&#39;t require permission and\nwill start listening as soon as the request fires; browsers with no\nsensor at all simply never report a reading.</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-request-on-click\">Request on click</h4>\n<p><include-content data-demo=\"request\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/provider-orientation",
+    "shortName": "provider-orientation",
+    "version": "0.1.0",
+    "description": "<provider-orientation> 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-orientation@0.1.0/dist/index.umd.min.js\"></script>",
+    "install": {
+      "npm": "npm install @excom/provider-orientation"
+    },
+    "imports": {
+      "js": "import \"@excom/provider-orientation\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/provider-orientation\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/provider-orientation\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "provider-orientation",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "compass-throttle-ms",
+          "type": "number",
+          "description": "Minimum ms between <code>provider-orientation-success</code> updates. Android can fire <code>deviceorientationabsolute</code> at 60-200 Hz; without throttling that floods listeners and CSS/Quark bindings.",
+          "fieldName": "compassThrottleMs",
+          "surface": "option",
+          "default": "100"
+        },
+        {
+          "name": "is-paused",
+          "type": "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 <code>provider-orientation-request</code> from a click handler instead (see class docs).",
+          "fieldName": "isPaused",
+          "surface": "option"
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "The permission request was denied, or listening failed to start.",
+          "fieldName": "isError",
+          "surface": "state"
+        },
+        {
+          "name": "is-requesting",
+          "type": "boolean",
+          "description": "iOS only: the permission request is pending (between <code>provider-orientation-request</code> and the user&#39;s response).",
+          "fieldName": "isRequesting",
+          "surface": "state"
+        },
+        {
+          "name": "is-success",
+          "type": "boolean",
+          "description": "Listening for orientation updates (permission granted where required). Stays set across updates.",
+          "fieldName": "isSuccess",
+          "surface": "state"
+        }
+      ],
+      "events": [
+        {
+          "name": "provider-orientation-error",
+          "description": "Dispatched when the permission request is denied, or fails for any other reason.",
+          "type": "ProviderOrientationErrorEvent",
+          "typeExpanded": "CustomEvent & { type: \"provider-orientation-error\"; detail: string | Error; 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-orientation-success",
+          "description": "Dispatched on every compass update (throttled by <code>compass-throttle-ms</code>). <code>bearing</code> is normalized 0-360°; <code>alpha</code> is the raw <code>DeviceOrientationEvent.alpha</code> where available.",
+          "type": "ProviderOrientationSuccessEvent",
+          "typeExpanded": "CustomEvent & { type: \"provider-orientation-success\"; detail: { bearing: number; alpha: number | null; }; bubbles: true; cancelable: true; composed: true }",
+          "defaultAction": "Stores <code>{ bearing, alpha }</code> 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": "Requests permission (iOS) and starts listening for orientation updates. Invoke it from a button (<code>&lt;button command=&quot;--request&quot; commandfor=&quot;…&quot;&gt;</code>) so the user activation is there."
+        }
+      ],
+      "defaultActions": [
+        {
+          "name": "provider-orientation-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-orientation-success",
+          "description": "Stores <code>{ bearing, alpha }</code> in <code>provision</code> and sets <code>is-success</code> (clearing <code>is-requesting</code> / <code>is-error</code>)."
+        }
+      ],
+      "expectedChildren": [],
+      "provisions": [
+        {
+          "name": "provision",
+          "type": "ProviderOrientationSuccess",
+          "typeExpanded": "{ bearing: number; alpha: number | null; }",
+          "description": "Latest reading: <code>{ bearing, alpha }</code> on success, or the error on failure. Not reflected as an attribute.",
+          "fieldName": "provision"
+        }
+      ]
+    }
+  ],
+  "exportedFiles": {}
+}