@inglorious/web 6.0.1 → 6.1.0

package/LICENSE

@@ -1,9 +1,9 @@
-The MIT License (MIT)
-
-Copyright © 2025 Inglorious Coderz Srl.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+The MIT License (MIT)
+
+Copyright © 2025 Inglorious Coderz Srl.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -7,7 +7,7 @@ A lightweight, reactive-enough web framework built on **pure JavaScript**, the e
 
 Unlike modern frameworks that invent their own languages or rely on signals, proxies, or compilers, **@inglorious/web embraces plain JavaScript** and a transparent architecture.
 
-It's a **complete framework**: it ships with a client-side router, declarative forms, geolocation state, async helpers (via `@inglorious/store/async`), and a dedicated testing utilities entry point (`@inglorious/web/test`) that re-exports `trigger` from `@inglorious/store` and `render` from `lit-html`. UI primitives (controls, data display, navigation, feedback, layout, surfaces) live in the companion package **[Inglorious UI](https://inglorious.dev/ui)**.
+It's a **complete framework**: it ships with a client-side router, declarative forms, geolocation and compass state, async helpers (via `@inglorious/store/async`), and a dedicated testing utilities entry point (`@inglorious/web/test`) that re-exports `trigger` from `@inglorious/store` and `render` from `lit-html`. UI primitives (controls, data display, navigation, feedback, layout, surfaces) live in the companion package **[Inglorious UI](https://inglorious.dev/ui)**.
 
 ---
 
@@ -28,10 +28,10 @@ It's a **complete framework**: it ships with a client-side router, declarative f
   Zero magic, zero reactivity graphs, zero compiler.  
   Just JavaScript functions and store events.
 
-- **Router, Forms, Geolocation, Async, Testing utilities**  
+- **Router, Forms, Geolocation, Compass, Async, Testing utilities**
   High-level primitives built on the same predictable model. UI primitives (tables, virtual lists, comboboxes, and more) live in **[Inglorious UI](https://inglorious.dev/ui)**.
 
-- **Zero Component State**  
+- **Zero Component State**
   All state lives in the store — never inside components.
 
 - **No Signals, No Subscriptions, No Framework-Level Memory Leaks**  
@@ -1259,18 +1259,145 @@ The entity state contains:
 
 Events:
 
-- `#geolocation:getCurrentPosition` — request the current position
-- `#geolocation:watch` — start watching position changes
-- `#geolocation:clearWatch` — stop the active watch
+- `geolocationRequest` — request the current position
+- `geolocationWatch` — start watching position changes
+- `geolocationUnwatch` — stop the active watch
 
 ```javascript
-api.notify("#geolocation:getCurrentPosition", {
+api.notify("geolocationRequest", {
   enableHighAccuracy: true,
   timeout: 5000,
 })
 
-api.notify("#geolocation:watch")
-api.notify("#geolocation:clearWatch")
+api.notify("geolocationWatch")
+api.notify("geolocationUnwatch")
+```
+
+### Example: Show current location
+
+```javascript
+import { mount, html } from "@inglorious/web"
+import { store } from "./store.js"
+
+const renderApp = (api) => {
+  const geolocation = api.getEntity("geolocation")
+  const position = geolocation.position
+
+  return html`
+    <section>
+      <h2>Geolocation</h2>
+      <p>Supported: ${geolocation.isSupported ? "yes" : "no"}</p>
+      <p>Loading: ${geolocation.isLoading ? "yes" : "no"}</p>
+      <p>
+        Position:
+        ${position
+          ? html`${position.coords.latitude.toFixed(4)},
+            ${position.coords.longitude.toFixed(4)}`
+          : "unknown"}
+      </p>
+      <p>Error: ${geolocation.error ? geolocation.error.message : "none"}</p>
+      <button
+        @click=${() =>
+          api.notify("geolocationRequest", {
+            enableHighAccuracy: true,
+            timeout: 5000,
+          })}
+      >
+        Request Current Position
+      </button>
+      <button @click=${() => api.notify("geolocationWatch")}>
+        Start Watch
+      </button>
+      <button @click=${() => api.notify("geolocationUnwatch")}>
+        Stop Watch
+      </button>
+    </section>
+  `
+}
+
+mount(store, renderApp, document.getElementById("root"))
+```
+
+---
+
+## Compass
+
+`@inglorious/web` also includes a `Compass` type for managing device orientation and heading state inside the store.
+
+```javascript
+import { createStore } from "@inglorious/store"
+import { Compass } from "@inglorious/web/compass"
+
+const store = createStore({
+  types: { Compass },
+  autoCreateEntities: true,
+})
+
+// The store now contains a `compass` entity.
+store.getState().compass
+```
+
+The entity state contains:
+
+- `isSupported` — whether device orientation sensors are available
+- `isLoading` — whether permissions or heading data are pending
+- `isCompassPermissionGranted` — whether compass permission has been granted
+- `isCompassActive` — whether a valid heading is currently active
+- `heading` — the latest heading in degrees, or `null`
+- `error` — the latest normalized `{ code, message }` error
+- `manualOffset` — a heading offset in degrees to apply to raw sensor values
+
+Events:
+
+- `compassPermissionsRequest` — request compass permission when needed
+- `compassWatch` — start listening for device orientation events
+- `compassUnwatch` — stop listening for device orientation events
+- `compassPermissionsGrant` — set permission granted
+- `compassActiveChange` — update active/inactive state
+- `compassHeadingChange` — update the latest heading
+- `compassError` — store a normalized compass error
+
+```javascript
+api.notify("compassPermissionsRequest")
+api.notify("compassWatch")
+api.notify("compassUnwatch")
+```
+
+### Example: Show heading and request permission
+
+```javascript
+import { mount, html } from "@inglorious/web"
+import { store } from "./store.js"
+
+const renderApp = (api) => {
+  const compass = api.getEntity("compass")
+
+  return html`
+    <section>
+      <h2>Compass</h2>
+      <p>Supported: ${compass.isSupported ? "yes" : "no"}</p>
+      <p>
+        Permission:
+        ${compass.isCompassPermissionGranted ? "granted" : "unknown"}
+      </p>
+      <p>Active: ${compass.isCompassActive ? "yes" : "no"}</p>
+      <p>
+        Heading:
+        ${compass.heading !== null
+          ? `${compass.heading.toFixed(1)}°`
+          : "unknown"}
+      </p>
+      <p>Error: ${compass.error ? compass.error.message : "none"}</p>
+      <button @click=${() => api.notify("compassPermissionsRequest")}>
+        Request Permission
+      </button>
+      <button @click=${() => api.notify("compassWatch")}>Start Compass</button>
+      <button @click=${() => api.notify("compassUnwatch")}>Stop Compass</button>
+    </section>
+  `
+}
+
+mount(store, renderApp, document.getElementById("root"))
 ```
 
 ---
@@ -1621,6 +1748,8 @@ import { render, trigger } from "@inglorious/web/test"
 
 import { Form } from "@inglorious/web/form"
 import { Router, setRoutes } from "@inglorious/web/router"
+import { Geolocation } from "@inglorious/web/geolocation"
+import { Compass } from "@inglorious/web/compass"
 ```
 
 This keeps `lit-html` as an internal implementation detail while still giving applications stable, tree-shakeable import paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.0.1",
+  "version": "6.1.0",
   "description": "A new web framework that leverages the power of the Inglorious Store combined with the performance and simplicity of lit-html.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -26,6 +26,10 @@
       "types": "./types/index.d.ts",
       "import": "./src/index.js"
     },
+    "./compass": {
+      "types": "./types/compass.d.ts",
+      "import": "./src/compass/index.js"
+    },
     "./directives/*": {
       "types": "./types/directives/*.d.ts",
       "import": "./src/directives/*.js"

package/src/compass/handlers.js

@@ -0,0 +1,206 @@
+/**
+ * @typedef {import("../../types/compass.js").CompassEntity} CompassEntity
+ * @typedef {import("../../types/compass.js").CompassError} CompassError
+ */
+
+const COMPASS_TIMEOUT = 3000
+const NO_TIMEOUT = null
+
+const FULL_CIRCLE = 360
+const DEFAULT_ORIENTATION = 0
+const DEFAULT_ERROR_CODE = 0
+
+export function create(entity) {
+  entity.error ??= null
+  entity.heading ??= null
+  entity.isCompassActive ??= false
+  entity.isCompassPermissionGranted ??= false
+  entity.isLoading ??= false
+  entity.isSupported = isCompassSupported()
+  entity.manualOffset ??= 0
+  entity._absoluteListener ??= null
+  entity._orientationListener ??= null
+  // True once a deviceorientationabsolute event fires; used to drop the
+  // fallback deviceorientation listener so only one path updates heading.
+  entity._isUsingAbsolute ??= false
+  entity.compassTimeout ??= NO_TIMEOUT
+}
+
+export function destroy(entity) {
+  compassUnwatch(entity)
+}
+
+export function compassUnwatch(entity) {
+  const win = getWindow()
+
+  if (entity._orientationListener && win) {
+    win.removeEventListener("deviceorientation", entity._orientationListener)
+  }
+
+  if (entity._absoluteListener && win) {
+    win.removeEventListener(
+      "deviceorientationabsolute",
+      entity._absoluteListener,
+    )
+  }
+
+  if (entity.compassTimeout !== NO_TIMEOUT) {
+    clearTimeout(entity.compassTimeout)
+  }
+
+  entity.isLoading = false
+  entity.isCompassActive = false
+  entity.compassTimeout = NO_TIMEOUT
+  entity._orientationListener = null
+  entity._absoluteListener = null
+  entity._isUsingAbsolute = false
+}
+
+export function compassError(entity, error) {
+  entity.error = normalizeError(error)
+  entity.isLoading = false
+  entity.isCompassPermissionGranted = false
+}
+
+export async function compassPermissionsRequest(entity, _, api) {
+  entity.isSupported = isCompassSupported()
+  entity.error = null
+
+  if (!entity.isSupported) {
+    entity.isLoading = false
+    api.notify("compassError", createUnsupportedError())
+    return
+  }
+
+  entity.isLoading = true
+
+  if (
+    typeof DeviceOrientationEvent !== "undefined" &&
+    typeof DeviceOrientationEvent.requestPermission === "function"
+  ) {
+    try {
+      const permission = await DeviceOrientationEvent.requestPermission()
+      if (permission === "granted") {
+        api.notify("compassPermissionsGrant")
+      } else {
+        entity.isLoading = false
+        api.notify("compassError", createPermissionDeniedError())
+      }
+    } catch (error) {
+      entity.isLoading = false
+      api.notify("compassError", normalizeError(error))
+    }
+  } else {
+    api.notify("compassPermissionsGrant")
+  }
+}
+
+export function compassPermissionsGrant(entity) {
+  entity.isLoading = false
+  entity.isCompassPermissionGranted = true
+}
+
+export function compassWatch(entity, _, api) {
+  entity._isUsingAbsolute = false
+
+  const orientationListener = createOrientationChangeListener(entity, api)
+  const absoluteListener = (event) => {
+    if (!entity._isUsingAbsolute) {
+      entity._isUsingAbsolute = true
+      getWindow()?.removeEventListener("deviceorientation", orientationListener)
+    }
+
+    orientationListener(event)
+  }
+
+  entity._orientationListener = orientationListener
+  entity._absoluteListener = absoluteListener
+
+  const win = getWindow()
+  win?.addEventListener("deviceorientationabsolute", absoluteListener)
+  win?.addEventListener("deviceorientation", orientationListener)
+
+  entity.compassTimeout = globalThis.setTimeout(
+    () => checkTimeout(entity, api),
+    COMPASS_TIMEOUT,
+  )
+}
+
+function checkTimeout(entity, api) {
+  entity.compassTimeout = NO_TIMEOUT
+
+  if (!entity.heading) {
+    api.notify("compassActiveChange", false)
+  }
+}
+
+export function compassActiveChange(entity, value) {
+  entity.isCompassActive = value
+}
+
+export function compassHeadingChange(entity, value) {
+  entity.isLoading = false
+  entity.heading = value
+}
+
+function createOrientationChangeListener(entity, api) {
+  return (event) => {
+    const heading = event?.alpha
+    if (typeof heading !== "number") {
+      return
+    }
+
+    if (entity.compassTimeout !== NO_TIMEOUT) {
+      clearTimeout(entity.compassTimeout)
+      entity.compassTimeout = NO_TIMEOUT
+    }
+
+    const screenAngle = getScreenAngle()
+    const adjustedHeading =
+      (((heading - screenAngle + entity.manualOffset) % FULL_CIRCLE) +
+        FULL_CIRCLE) %
+      FULL_CIRCLE
+
+    api.notify("compassActiveChange", true)
+    api.notify("compassHeadingChange", Math.round(adjustedHeading))
+  }
+}
+
+function getWindow() {
+  return typeof window !== "undefined" ? window : null
+}
+
+function getScreenAngle() {
+  const win = getWindow()
+  return (
+    win?.screen?.orientation?.angle ?? win?.orientation ?? DEFAULT_ORIENTATION
+  )
+}
+
+function isCompassSupported() {
+  return (
+    typeof DeviceOrientationEvent !== "undefined" &&
+    Boolean(getWindow()?.addEventListener)
+  )
+}
+
+function createUnsupportedError() {
+  return {
+    code: 0,
+    message: "Compass is not supported by this environment.",
+  }
+}
+
+function createPermissionDeniedError() {
+  return {
+    code: 1,
+    message: "Compass permission denied.",
+  }
+}
+
+function normalizeError(error) {
+  return {
+    code: error?.code ?? DEFAULT_ERROR_CODE,
+    message: error?.message ?? String(error),
+  }
+}

package/src/compass/index.js

@@ -0,0 +1,3 @@
+import * as handlers from "./handlers.js"
+
+export const Compass = { ...handlers }

package/src/geolocation/handlers.js

@@ -6,22 +6,6 @@
 
 const NO_WATCH_ID = null
 
-/**
- * Stops an active geolocation watch.
- * @param {GeolocationEntity} entity - The geolocation entity.
- */
-export function unwatch(entity) {
-  const geolocation = getGeolocation()
-
-  if (entity.watchId !== NO_WATCH_ID && geolocation) {
-    geolocation.clearWatch(entity.watchId)
-  }
-
-  entity.isLoading = false
-  entity.isWatching = false
-  entity.watchId = NO_WATCH_ID
-}
-
 /**
  * Initializes the geolocation entity with default state.
  * @param {GeolocationEntity} entity - The geolocation entity.
@@ -40,7 +24,7 @@ export function create(entity) {
  * @param {GeolocationEntity} entity - The geolocation entity.
  */
 export function destroy(entity) {
-  unwatch(entity)
+  geolocationUnwatch(entity)
 }
 
 /**
@@ -48,7 +32,7 @@ export function destroy(entity) {
  * @param {GeolocationEntity} entity - The geolocation entity.
  * @param {GeolocationPositionError} error - The geolocation error.
  */
-export function error(entity, error) {
+export function geolocationError(entity, error) {
   entity.error = normalizeError(error)
   entity.isLoading = false
 }
@@ -59,7 +43,7 @@ export function error(entity, error) {
  * @param {GeolocationOptions} options - Position options.
  * @param {{ notify: Function }} api - The store API.
  */
-export function request(entity, options = {}, api) {
+export function geolocationRequest(entity, options = {}, api) {
   const geolocation = getGeolocation()
 
   entity.isSupported = Boolean(geolocation)
@@ -67,7 +51,7 @@ export function request(entity, options = {}, api) {
 
   if (!geolocation) {
     entity.isLoading = false
-    api.notify(`#${entity.id}:error`, createUnsupportedError())
+    api.notify("geolocationError", createUnsupportedError())
     return
   }
 
@@ -75,10 +59,10 @@ export function request(entity, options = {}, api) {
 
   geolocation.getCurrentPosition(
     (position) => {
-      api.notify(`#${entity.id}:success`, normalizePosition(position))
+      api.notify("geolocationSuccess", normalizePosition(position))
     },
     (error) => {
-      api.notify(`#${entity.id}:error`, error)
+      api.notify("geolocationError", error)
     },
     options,
   )
@@ -89,19 +73,35 @@ export function request(entity, options = {}, api) {
  * @param {GeolocationEntity} entity - The geolocation entity.
  * @param {GeolocationPosition} position - The geolocation position.
  */
-export function success(entity, position) {
+export function geolocationSuccess(entity, position) {
   entity.error = null
   entity.isLoading = false
   entity.position = position
 }
 
+/**
+ * Stops an active geolocation watch.
+ * @param {GeolocationEntity} entity - The geolocation entity.
+ */
+export function geolocationUnwatch(entity) {
+  const geolocation = getGeolocation()
+
+  if (entity.watchId !== NO_WATCH_ID && geolocation) {
+    geolocation.clearWatch(entity.watchId)
+  }
+
+  entity.isLoading = false
+  entity.isWatching = false
+  entity.watchId = NO_WATCH_ID
+}
+
 /**
  * Starts watching geolocation changes.
  * @param {GeolocationEntity} entity - The geolocation entity.
  * @param {GeolocationOptions} options - Watch options.
  * @param {{ notify: Function }} api - The store API.
  */
-export function watch(entity, options = {}, api) {
+export function geolocationWatch(entity, options = {}, api) {
   const geolocation = getGeolocation()
 
   entity.isSupported = Boolean(geolocation)
@@ -109,7 +109,7 @@ export function watch(entity, options = {}, api) {
 
   if (!geolocation) {
     entity.isLoading = false
-    api.notify(`#${entity.id}:error`, createUnsupportedError())
+    api.notify("geolocationError", createUnsupportedError())
     return
   }
 
@@ -121,10 +121,10 @@ export function watch(entity, options = {}, api) {
   entity.isWatching = true
   entity.watchId = geolocation.watchPosition(
     (position) => {
-      api.notify(`#${entity.id}:success`, normalizePosition(position))
+      api.notify("geolocationSuccess", normalizePosition(position))
     },
     (error) => {
-      api.notify(`#${entity.id}:error`, error)
+      api.notify("geolocationError", error)
     },
     options,
   )

package/types/compass.d.ts

@@ -0,0 +1,44 @@
+import { Api } from "./mount"
+
+export interface CompassEntity {
+  id: string | number
+  type?: "Compass"
+  error: CompassError | null
+  heading: number | null
+  isCompassActive: boolean
+  isCompassPermissionGranted: boolean
+  isLoading: boolean
+  isSupported: boolean
+  manualOffset: number | null
+  _absoluteListener: ((event: DeviceOrientationEvent) => void) | null
+  _orientationListener: ((event: DeviceOrientationEvent) => void) | null
+  _isUsingAbsolute: boolean
+  compassTimeout: number | null
+}
+
+export interface CompassError {
+  code: number
+  message: string
+}
+
+export interface CompassType {
+  create(entity: CompassEntity, payload: unknown, api: Api): void
+  destroy(entity: CompassEntity, payload: unknown, api: Api): void
+  compassUnwatch(entity: CompassEntity, payload: unknown, api: Api): void
+  compassError(entity: CompassEntity, error: CompassError, api: Api): void
+  compassPermissionsRequest(
+    entity: CompassEntity,
+    payload: unknown,
+    api: Api,
+  ): void
+  compassPermissionsGrant(
+    entity: CompassEntity,
+    payload: unknown,
+    api: Api,
+  ): void
+  compassWatch(entity: CompassEntity, payload: unknown, api: Api): void
+  compassActiveChange(entity: CompassEntity, value: boolean, api: Api): void
+  compassHeadingChange(entity: CompassEntity, value: number, api: Api): void
+}
+
+export declare const Compass: CompassType

package/types/geolocation.d.ts

@@ -1,3 +1,5 @@
+import { Api } from "./mount"
+
 export interface GeolocationCoordinates {
   accuracy: number
   altitude: number | null
@@ -43,13 +45,13 @@ export interface GeolocationType {
   request(
     entity: GeolocationEntity,
     options: GeolocationOptions | undefined,
-    api: { notify: (event: string, payload?: unknown) => void },
+    api: Api,
   ): void
   success(entity: GeolocationEntity, position: GeolocationPosition): void
   watch(
     entity: GeolocationEntity,
     options: GeolocationOptions | undefined,
-    api: { notify: (event: string, payload?: unknown) => void },
+    api: Api,
   ): void
 }