@inglorious/web 6.0.0 → 6.0.2

package/README.md

@@ -7,6 +7,8 @@ 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)**.
+
 ---
 
 ## Features
@@ -26,8 +28,8 @@ Unlike modern frameworks that invent their own languages or rely on signals, pro
   Zero magic, zero reactivity graphs, zero compiler.  
   Just JavaScript functions and store events.
 
-- **Router, Forms, Tables, Virtual Lists**  
-  High-level primitives built on the same predictable model.
+- **Router, Forms, Geolocation, 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**  
   All state lives in the store — never inside components.
@@ -347,7 +349,12 @@ One of Inglorious Web's greatest strengths is **testability**. Entity handlers a
 
 ### Testing Utilities
 
-Inglorious Web provides two simple utilities for testing via `@inglorious/web/test`:
+The `@inglorious/web/test` entry point re-exports two helpers so you can test handlers and templates without any extra setup:
+
+- **`trigger`** — comes from `@inglorious/store` (`@inglorious/store/test`). It executes an entity handler and returns the new state plus any dispatched events.
+- **`render`** — comes from `lit-html`. It renders a template to a DOM node so you can assert on its output.
+
+Both are re-exported from `@inglorious/web/test` purely as a convenience, so a web app only needs to depend on `@inglorious/web` to test its handlers and templates.
 
 #### `trigger(entity, handler, payload?, api?)`
 
@@ -1224,6 +1231,50 @@ For ready-made UI primitives (controls, data display, navigation, feedback, layo
 
 ---
 
+## Geolocation
+
+`@inglorious/web` includes a `Geolocation` type for keeping browser geolocation state inside the store.
+
+```javascript
+import { createStore } from "@inglorious/store"
+import { Geolocation } from "@inglorious/web/geolocation"
+
+const store = createStore({
+  types: { Geolocation },
+  autoCreateEntities: true,
+})
+
+// The store now contains a `geolocation` entity.
+store.getState().geolocation
+```
+
+The entity state contains:
+
+- `isSupported` — whether `navigator.geolocation` is available
+- `isLoading` — whether a current-position request or first watch result is pending
+- `isWatching` — whether a geolocation watch is active
+- `position` — the latest normalized `{ coords, timestamp }` value
+- `error` — the latest normalized `{ code, message }` error
+- `watchId` — the active browser watch id, or `null`
+
+Events:
+
+- `#geolocation:getCurrentPosition` — request the current position
+- `#geolocation:watch` — start watching position changes
+- `#geolocation:clearWatch` — stop the active watch
+
+```javascript
+api.notify("#geolocation:getCurrentPosition", {
+  enableHighAccuracy: true,
+  timeout: 5000,
+})
+
+api.notify("#geolocation:watch")
+api.notify("#geolocation:clearWatch")
+```
+
+---
+
 ## Forms
 
 `@inglorious/web` includes a small but powerful `form` type for managing form state inside your entity store. It offers:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "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",
@@ -34,6 +34,10 @@
       "types": "./types/form.d.ts",
       "import": "./src/form/index.js"
     },
+    "./geolocation": {
+      "types": "./types/geolocation.d.ts",
+      "import": "./src/geolocation/index.js"
+    },
     "./hydrate": "./src/hydrate.js",
     "./router": {
       "types": "./types/router.d.ts",

package/src/geolocation/handlers.js

@@ -0,0 +1,170 @@
+/**
+ * @typedef {import("../../types/geolocation.js").GeolocationEntity} GeolocationEntity
+ * @typedef {import("../../types/geolocation.js").GeolocationOptions} GeolocationOptions
+ * @typedef {import("../../types/geolocation.js").GeolocationPosition} GeolocationPosition
+ */
+
+const NO_WATCH_ID = null
+
+/**
+ * Initializes the geolocation entity with default state.
+ * @param {GeolocationEntity} entity - The geolocation entity.
+ */
+export function create(entity) {
+  entity.error ??= null
+  entity.isLoading ??= false
+  entity.isSupported = Boolean(getGeolocation())
+  entity.isWatching ??= false
+  entity.position ??= null
+  entity.watchId ??= NO_WATCH_ID
+}
+
+/**
+ * Clears the geolocation watch before the entity is destroyed.
+ * @param {GeolocationEntity} entity - The geolocation entity.
+ */
+export function destroy(entity) {
+  unwatch(entity)
+}
+
+/**
+ * Stores a normalized geolocation error.
+ * @param {GeolocationEntity} entity - The geolocation entity.
+ * @param {GeolocationPositionError} error - The geolocation error.
+ */
+export function error(entity, error) {
+  entity.error = normalizeError(error)
+  entity.isLoading = false
+}
+
+/**
+ * Requests the current geolocation position.
+ * @param {GeolocationEntity} entity - The geolocation entity.
+ * @param {GeolocationOptions} options - Position options.
+ * @param {{ notify: Function }} api - The store API.
+ */
+export function request(entity, options = {}, api) {
+  const geolocation = getGeolocation()
+
+  entity.isSupported = Boolean(geolocation)
+  entity.error = null
+  const entityId = entity.id
+
+  if (!geolocation) {
+    entity.isLoading = false
+    api.notify(`#${entityId}:error`, createUnsupportedError())
+    return
+  }
+
+  entity.isLoading = true
+
+  geolocation.getCurrentPosition(
+    (position) => {
+      api.notify(`#${entityId}:success`, normalizePosition(position))
+    },
+    (error) => {
+      api.notify(`#${entityId}:error`, error)
+    },
+    options,
+  )
+}
+
+/**
+ * Stores a normalized geolocation position.
+ * @param {GeolocationEntity} entity - The geolocation entity.
+ * @param {GeolocationPosition} position - The geolocation position.
+ */
+export function success(entity, position) {
+  entity.error = null
+  entity.isLoading = false
+  entity.position = position
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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) {
+  const geolocation = getGeolocation()
+
+  entity.isSupported = Boolean(geolocation)
+  entity.error = null
+  const entityId = entity.id
+
+  if (!geolocation) {
+    entity.isLoading = false
+    api.notify(`#${entityId}:error`, createUnsupportedError())
+    return
+  }
+
+  if (entity.watchId !== NO_WATCH_ID) {
+    return
+  }
+
+  entity.isLoading = true
+  entity.isWatching = true
+  entity.watchId = geolocation.watchPosition(
+    (position) => {
+      api.notify(`#${entityId}:success`, normalizePosition(position))
+    },
+    (error) => {
+      api.notify(`#${entityId}:error`, error)
+    },
+    options,
+  )
+}
+
+function createUnsupportedError() {
+  return {
+    code: 0,
+    message: "Geolocation is not supported by this environment.",
+  }
+}
+
+function getGeolocation() {
+  return globalThis.navigator?.geolocation
+}
+
+function normalizeCoords(coords) {
+  return {
+    accuracy: coords.accuracy,
+    altitude: coords.altitude,
+    altitudeAccuracy: coords.altitudeAccuracy,
+    heading: coords.heading,
+    latitude: coords.latitude,
+    longitude: coords.longitude,
+    speed: coords.speed,
+  }
+}
+
+function normalizeError(error) {
+  return {
+    code: error.code,
+    message: error.message,
+  }
+}
+
+function normalizePosition(position) {
+  return {
+    coords: normalizeCoords(position.coords),
+    timestamp: position.timestamp,
+  }
+}

package/src/geolocation/index.js

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

package/types/geolocation.d.ts

@@ -0,0 +1,56 @@
+export interface GeolocationCoordinates {
+  accuracy: number
+  altitude: number | null
+  altitudeAccuracy: number | null
+  heading: number | null
+  latitude: number
+  longitude: number
+  speed: number | null
+}
+
+export interface GeolocationEntity {
+  error: GeolocationError | null
+  id: string | number
+  isLoading: boolean
+  isSupported: boolean
+  isWatching: boolean
+  position: GeolocationPosition | null
+  type?: "Geolocation"
+  watchId: number | null
+}
+
+export interface GeolocationError {
+  code: number
+  message: string
+}
+
+export interface GeolocationOptions {
+  enableHighAccuracy?: boolean
+  maximumAge?: number
+  timeout?: number
+}
+
+export interface GeolocationPosition {
+  coords: GeolocationCoordinates
+  timestamp: number
+}
+
+export interface GeolocationType {
+  unwatch(entity: GeolocationEntity): void
+  create(entity: GeolocationEntity): void
+  destroy(entity: GeolocationEntity): void
+  error(entity: GeolocationEntity, error: GeolocationError): void
+  request(
+    entity: GeolocationEntity,
+    options: GeolocationOptions | undefined,
+    api: { notify: (event: string, payload?: unknown) => void },
+  ): void
+  success(entity: GeolocationEntity, position: GeolocationPosition): void
+  watch(
+    entity: GeolocationEntity,
+    options: GeolocationOptions | undefined,
+    api: { notify: (event: string, payload?: unknown) => void },
+  ): void
+}
+
+export declare const Geolocation: GeolocationType