@inglorious/web 5.0.2 → 6.0.1

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.
@@ -283,7 +285,8 @@ First, set up your store with entity types. For each type you want to render, ad
 
 ```javascript
 // store.js
-import { createStore, html } from "@inglorious/web"
+import { createStore } from "@inglorious/store"
+import { html } from "@inglorious/web"
 
 const types = {
   counter: {
@@ -346,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?)`
 
@@ -503,7 +511,7 @@ test("completed todo has completed class", () => {
 #### Integration Test: Full Store
 
 ```javascript
-import { createStore } from "@inglorious/web"
+import { createStore } from "@inglorious/store"
 import { Counter } from "./types/counter.js"
 
 test("full user interaction flow", () => {
@@ -527,7 +535,7 @@ test("full user interaction flow", () => {
 #### Testing Computed State
 
 ```javascript
-import { compute } from "@inglorious/store"
+import { compute } from "@inglorious/store/select"
 
 test("filtered todos excludes completed", () => {
   const todos = [
@@ -852,7 +860,6 @@ export const App = {
   create(entity) {
     entity.title = "Todos"
   },
-
   render(entity, api) {
     return html`
       <div>
@@ -916,7 +923,7 @@ To enable DevTools, add the middleware provided by `createDevtools()`.
 
 ```javascript
 // middlewares.js
-import { createDevtools } from "@inglorious/web"
+import { createDevtools } from "@inglorious/store/client/devtools"
 
 export const middlewares = []
 
@@ -930,7 +937,7 @@ if (import.meta.env.DEV) {
 
 ```javascript
 // store.js
-import { createStore } from "@inglorious/web"
+import { createStore } from "@inglorious/store"
 import { middlewares } from "./middlewares.js"
 
 export const store = createStore({
@@ -962,14 +969,13 @@ To enable the router, add it to your store's types and create a `router` entity.
 
 ```javascript
 // store.js
-import { createStore, html } from "@inglorious/web"
+import { createStore } from "@inglorious/store"
+import { html } from "@inglorious/web"
 import { Router, setRoutes } from "@inglorious/web/router"
 
 const types = {
   // 1. Add the router type to your store's types
-  Router,
-
-  // 2. Define types for your pages
+  Router, // 2. Define types for your pages
   HomePage: {
     render: () => html`<h1>Welcome Home!</h1>`,
   },
@@ -1062,8 +1068,7 @@ const entities = {
 export const store = createStore({ types, entities })
 
 setRoutes({
-  "/": "homePage",
-  // Lazy load: returns a Promise resolving to a module
+  "/": "homePage", // Lazy load: returns a Promise resolving to a module
   "/admin": () => import("./pages/admin.js"),
 })
 ```
@@ -1115,19 +1120,15 @@ export const requireAuth = (type) => ({
 
 ```javascript
 // store.js
-import { createStore } from "@inglorious/web"
+import { createStore } from "@inglorious/store"
 import { Router } from "@inglorious/web/router"
 import { requireAuth } from "./guards/require-auth.js"
 import { AdminPage } from "./pages/admin.js"
 import { LoginPage } from "./pages/login.js"
 
 const types = {
-  Router,
-
-  // Public page - no guard
-  LoginPage,
-
-  // Protected page - composed with requireAuth guard
+  Router, // Public page - no guard
+  LoginPage, // Protected page - composed with requireAuth guard
   AdminPage: [AdminPage, requireAuth],
 }
 
@@ -1173,9 +1174,7 @@ You can compose multiple guards for fine-grained control:
 ```javascript
 const types = {
   // Require authentication AND admin role
-  AdminPage: [AdminPage, requireAuth, requireAdmin],
-
-  // Require authentication AND resource ownership
+  AdminPage: [AdminPage, requireAuth, requireAdmin], // Require authentication AND resource ownership
   UserProfile: [UserProfile, requireAuth, requireOwnership],
 }
 ```
@@ -1196,9 +1195,7 @@ const logging = (type) => ({
   render(entity, api) {
     console.log(`Rendering ${entity.id}`)
     return type.render(entity, api)
-  },
-
-  // Intercept any event
+  }, // Intercept any event
   someEvent(entity, payload, api) {
     console.log(`Event triggered on ${entity.id}`)
     type.someEvent?.(entity, payload, api)
@@ -1234,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:
@@ -1247,7 +1288,7 @@ For ready-made UI primitives (controls, data display, navigation, feedback, layo
 Include `form` in your `types` and create an entity for the form (use any id you like — `form` is used below for clarity):
 
 ```javascript
-import { createStore } from "@inglorious/web"
+import { createStore } from "@inglorious/store"
 import { Form } from "@inglorious/web/form"
 
 const types = { Form }
@@ -1334,11 +1375,9 @@ export const DataGrid = {
       </div>
     `
   },
-
   renderRow(entity, row, api) {
     return html`<div class="data-grid-row">${row.name}</div>`
   },
-
   rowClick(entity, row) {
     entity.selectedRow = row
   },
@@ -1441,14 +1480,11 @@ import "@shoelace-style/shoelace/dist/components/color-picker/color-picker.js"
 
 const types = {
   // App-specific type - full store integration
-  ProductTable,
-
-  // Web Component - for specialized UI
+  ProductTable, // Web Component - for specialized UI
   ThemeEditor: {
     colorChange(entity, color) {
       entity.primaryColor = color
     },
-
     render(entity, api) {
       return html`
         <div>
@@ -1482,13 +1518,11 @@ const types = {
       `
     },
   },
-
   Header: {
     render(entity, api) {
       return html`<header>${entity.title}</header>`
     },
   },
-
   Content: {
     render(entity, api) {
       return html`<main>${entity.text}</main>`
@@ -1518,7 +1552,6 @@ const Header = {
   create(entity) {
     entity.title = "Welcome"
   },
-
   render(entity, api) {
     return html`<header>${entity.title}</header>`
   },
@@ -1560,51 +1593,38 @@ The `renderFn` receives a powerful `api` object that contains all methods from t
 
 This method is the cornerstone of entity-based rendering. It looks up an entity by its `id`, finds its corresponding type definition, and calls the `render(entity, api)` method on that type. When you pass `typeName` and `Type`, it will lazily register the type with `api.setType(typeName, Type)` if the type is not already present.
 
-### Re-exported `lit-html` Utilities
+### Package Entry Points
+
+`@inglorious/web` keeps its root entry point intentionally small:
+
+```javascript
+import { mount, html, svg } from "@inglorious/web"
+```
 
-For convenience, `@inglorious/web` re-exports the most common utilities from `@inglorious/store` and `lit-html`, so you only need one import.
+Import everything else from the package that owns it, or from an explicit `@inglorious/web` subpath:
 
 ```javascript
-import {
-  // from @inglorious/store
-  createStore,
-  createDevtools,
-  compute,
-  createSelector, // for Redux compatibility
-  // from @inglorious/store/test
-  trigger,
-  // from lit-html
-  mount,
-  html,
-  svg,
-  // lit-html directives
-  choose,
-  classMap,
-  ref,
-  repeat,
-  styleMap,
-  unsafeHTML,
-  when,
-} from "@inglorious/web"
-
-// Subpath imports for tree-shaking
-import {
-  Form,
-  getFieldError,
-  getFieldValue,
-  isFieldTouched,
-} from "@inglorious/web/form"
-import {
-  Router,
-  getRoutes,
-  getRoute,
-  setRoutes,
-  addRoute,
-  removeRoute,
-} from "@inglorious/web/router"
+import { createStore } from "@inglorious/store"
+import { handleAsync } from "@inglorious/store/async"
+import { withOptimistic } from "@inglorious/store/optimistic"
+import { compute, createSelector } from "@inglorious/store/select"
+import { createDevtools } from "@inglorious/store/client/devtools"
+
+import { classMap } from "@inglorious/web/directives/class-map"
+import { ref, createRef } from "@inglorious/web/directives/ref"
+import { repeat } from "@inglorious/web/directives/repeat"
+import { styleMap } from "@inglorious/web/directives/style-map"
+import { unsafeHTML } from "@inglorious/web/directives/unsafe-html"
+import { when } from "@inglorious/web/directives/when"
+import { staticHtml, unsafeStatic } from "@inglorious/web/static"
 import { render, trigger } from "@inglorious/web/test"
+
+import { Form } from "@inglorious/web/form"
+import { Router, setRoutes } from "@inglorious/web/router"
 ```
 
+This keeps `lit-html` as an internal implementation detail while still giving applications stable, tree-shakeable import paths.
+
 ---
 
 ## Error Handling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "5.0.2",
+  "version": "6.0.1",
   "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,15 +26,27 @@
       "types": "./types/index.d.ts",
       "import": "./src/index.js"
     },
+    "./directives/*": {
+      "types": "./types/directives/*.d.ts",
+      "import": "./src/directives/*.js"
+    },
     "./form": {
       "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",
       "import": "./src/router/index.js"
     },
+    "./static": {
+      "types": "./types/static.d.ts",
+      "import": "./src/static.js"
+    },
     "./test": {
       "import": "./src/test.js"
     }
@@ -51,9 +63,11 @@
   "dependencies": {
     "@lit-labs/ssr-client": "^1.1.8",
     "lit-html": "^3.3.1",
-    "@inglorious/store": "10.0.0",
     "@inglorious/utils": "3.8.0"
   },
+  "peerDependencies": {
+    "@inglorious/store": "11.0.0"
+  },
   "devDependencies": {
     "prettier": "^3.6.2",
     "vitest": "^4.0.15",

package/src/directives/choose.js

@@ -0,0 +1 @@
+export { choose } from "lit-html/directives/choose.js"

package/src/directives/class-map.js

@@ -0,0 +1 @@
+export { classMap } from "lit-html/directives/class-map.js"

package/src/directives/ref.js

@@ -0,0 +1 @@
+export { createRef, ref } from "lit-html/directives/ref.js"

package/src/directives/repeat.js

@@ -0,0 +1 @@
+export { repeat } from "lit-html/directives/repeat.js"

package/src/directives/style-map.js

@@ -0,0 +1 @@
+export { styleMap } from "lit-html/directives/style-map.js"

package/src/directives/unsafe-html.js

@@ -0,0 +1 @@
+export { unsafeHTML } from "lit-html/directives/unsafe-html.js"

package/src/directives/when.js

@@ -0,0 +1 @@
+export { when } from "lit-html/directives/when.js"

package/src/geolocation/handlers.js

@@ -0,0 +1,168 @@
+/**
+ * @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
+
+/**
+ * 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.
+ */
+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
+
+  if (!geolocation) {
+    entity.isLoading = false
+    api.notify(`#${entity.id}:error`, createUnsupportedError())
+    return
+  }
+
+  entity.isLoading = true
+
+  geolocation.getCurrentPosition(
+    (position) => {
+      api.notify(`#${entity.id}:success`, normalizePosition(position))
+    },
+    (error) => {
+      api.notify(`#${entity.id}: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
+}
+
+/**
+ * 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
+
+  if (!geolocation) {
+    entity.isLoading = false
+    api.notify(`#${entity.id}:error`, createUnsupportedError())
+    return
+  }
+
+  if (entity.watchId !== NO_WATCH_ID) {
+    return
+  }
+
+  entity.isLoading = true
+  entity.isWatching = true
+  entity.watchId = geolocation.watchPosition(
+    (position) => {
+      api.notify(`#${entity.id}:success`, normalizePosition(position))
+    },
+    (error) => {
+      api.notify(`#${entity.id}: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/src/index.js

@@ -1,15 +1,2 @@
 export { mount } from "./mount.js"
-export { createStore } from "@inglorious/store"
-export { createDevtools } from "@inglorious/store/client/devtools.js"
-export { compute } from "@inglorious/store/select.js"
-export { createSelector } from "@inglorious/store/select.js"
-export { trigger } from "@inglorious/store/test.js"
 export { html, svg } from "lit-html"
-export { choose } from "lit-html/directives/choose.js"
-export { classMap } from "lit-html/directives/class-map.js"
-export { ref } from "lit-html/directives/ref.js"
-export { repeat } from "lit-html/directives/repeat.js"
-export { styleMap } from "lit-html/directives/style-map.js"
-export { unsafeHTML } from "lit-html/directives/unsafe-html.js"
-export { when } from "lit-html/directives/when.js"
-export { html as staticHtml, unsafeStatic } from "lit-html/static.js"

package/src/static.js

@@ -0,0 +1 @@
+export { html as staticHtml, unsafeStatic } from "lit-html/static.js"

package/types/directives/choose.d.ts

@@ -0,0 +1 @@
+export { choose } from "lit-html/directives/choose"

package/types/directives/class-map.d.ts

@@ -0,0 +1 @@
+export { classMap } from "lit-html/directives/class-map"

package/types/directives/ref.d.ts

@@ -0,0 +1 @@
+export { createRef, ref } from "lit-html/directives/ref"

package/types/directives/repeat.d.ts

@@ -0,0 +1 @@
+export { repeat } from "lit-html/directives/repeat"

package/types/directives/style-map.d.ts

@@ -0,0 +1 @@
+export { styleMap } from "lit-html/directives/style-map"

package/types/directives/unsafe-html.d.ts

@@ -0,0 +1 @@
+export { unsafeHTML } from "lit-html/directives/unsafe-html"

package/types/directives/when.d.ts

@@ -0,0 +1 @@
+export { when } from "lit-html/directives/when"

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

package/types/index.d.ts

@@ -1,5 +1,2 @@
-export * from "./form"
 export * from "./lit-html"
 export * from "./mount"
-export * from "./router"
-export * from "./store"

package/types/lit-html.d.ts

@@ -1,9 +1 @@
-export { html, TemplateResult } from "lit-html"
-
-export { choose } from "lit-html/directives/choose"
-export { classMap } from "lit-html/directives/class-map"
-export { ref } from "lit-html/directives/ref"
-export { repeat } from "lit-html/directives/repeat"
-export { styleMap } from "lit-html/directives/style-map"
-export { unsafeHTML } from "lit-html/directives/unsafe-html"
-export { when } from "lit-html/directives/when"
+export { html, svg, TemplateResult } from "lit-html"

package/types/static.d.ts

@@ -0,0 +1 @@
+export { html as staticHtml, unsafeStatic } from "lit-html/static"

package/types/store.d.ts

@@ -1,15 +0,0 @@
-export {
-  BaseEntity,
-  EntitiesState,
-  Event,
-  Middleware,
-  createStore,
-  TypesConfig,
-} from "@inglorious/store"
-
-export { compute } from "@inglorious/store/select"
-export { createSelector } from "@inglorious/store/select"
-export { trigger } from "@inglorious/store/test"
-
-export { createDevtools } from "@inglorious/store/client/devtools"
-export { multiplayerMiddleware } from "@inglorious/store/client/multiplayer-middleware"