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-mscaps update frequency (Android can fire 60-200 Hz) - iOS-aware Works with the required user-gesture permission flow
Installation
This package is available in the
<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/neutron@0.2.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/provider-orientation@0.1.4/dist/index.umd.min.js"></script>npm install @excom/provider-orientation<!-- import path to `node_modules` will depend on your build setup -->
<script type="module" src="/node_modules/@excom/provider-orientation"></script>
<link rel="stylesheet" href="/node_modules/@excom/provider-orientation">import "@excom/provider-orientation";Peer dependencies (0)
Packages a consumer must install alongside this one. Workspace deps are bundled.
| Package | Version |
|---|---|
|
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):
<button type="button" command="--request" commandfor="compass">
Enable compass
</button>
<provider-orientation id="compass" is-paused></provider-orientation><button type="button" command="--request" commandfor="compass">
Enable compass
</button>
<provider-orientation id="compass" is-paused></provider-orientation>compass-needle {
transform: rotate(calc(var(--bearing, 0) * 1deg));
}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
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
Provision
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events
Type
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements
Child or descendant elements are recognized by and relevant to its functionality.Styles
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
provider-orientation
Attributes (5)
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
compass-throttle-ms
Minimum ms between
provider-orientation-success updates. Android can fire deviceorientationabsolute at 60-200 Hz; without throttling that floods listeners and CSS/Quark bindings.
compassThrottleMs
number
100is-paused
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
falseis-error
The permission request was denied, or listening failed to start.
isError
boolean
falseis-requesting
iOS only: the permission request is pending (between
provider-orientation-request and the user's response).
isRequesting
boolean
falseis-success
Listening for orientation updates (permission granted where required). Stays set across updates.
isSuccess
boolean
falseProvision (1)
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
provision
Latest reading:
{ bearing, alpha } on success, or the error on failure. Not reflected as an attribute.
provision
ProviderOrientationSuccess
Events (3)
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
Type
provider-orientation-error
Dispatched when the permission request is denied, or fails for any other reason.
Type
ProviderOrientationErrorEvent
provision and sets is-error (clearing is-requesting / is-success).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
{ bearing, alpha } in provision and sets is-success (clearing is-requesting / is-error).command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
--request<button command="--request" commandfor="…">) so the user activation is there.
Recognized Elements (0)
Child or descendant elements are recognized by provider-orientation and relevant to its functionality.Styles (0)
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
Release notes (1)
0.1.1
- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources
Release notes
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.