@inglorious/web 2.5.0 → 2.6.1

package/README.md

@@ -19,6 +19,9 @@ Unlike modern frameworks that invent their own languages or rely on signals, pro
   Each entity type defines its own `render(entity, api)` method.  
   `api.render(id)` composes the UI by invoking the correct renderer for each entity.
 
+- **Type Composition**  
+  Types can be composed as arrays of behaviors, enabling reusable patterns like authentication guards, logging, or any cross-cutting concern.
+
 - **Simple and Predictable API**  
   Zero magic, zero reactivity graphs, zero compiler.  
   Just JavaScript functions and store events.
@@ -55,7 +58,7 @@ Use the scaffolder to create a starter app tailored to your workflow.
 
 ### ✨ **Inglorious Web re-renders the whole template tree on each state change.**
 
-Thanks to lit-html’s optimized diffing, this is fast, predictable, and surprisingly efficient.
+Thanks to lit-html's optimized diffing, this is fast, predictable, and surprisingly efficient.
 
 This means:
 
@@ -66,7 +69,7 @@ This means:
 
 You get Svelte-like ergonomic simplicity, but with no compiler and no magic.
 
-> “Re-render everything → let lit-html update only what changed.”
+> "Re-render everything → let lit-html update only what changed."
 
 It's that simple — and surprisingly fast in practice.
 
@@ -136,7 +139,7 @@ This makes it especially suitable for:
 
 # Comparison with Other Frameworks
 
-Here’s how @inglorious/web compares to the major players:
+Here's how @inglorious/web compares to the major players:
 
 ---
 
@@ -213,7 +216,7 @@ Inglorious Web is minimal, predictable, and tiny.
 
 ## **HTMX / Alpine / Vanilla DOM**
 
-You are closer philosophically to **HTMX** and **vanilla JS**, but with a declarative rendering model and entity-based state.
+Inglorious Web is closer philosophically to **HTMX** and **vanilla JS**, but with a declarative rendering model and entity-based state.
 
 ---
 
@@ -348,7 +351,7 @@ export const store = createStore({
 
 Now your application state is fully visible in the Redux DevTools browser extension.
 
-### What You’ll See in DevTools
+### What You'll See in DevTools
 
 - Each event you dispatch via `api.notify(event, payload)` will appear as an action in the DevTools timeline.
 - The entire store is visible under the _State_ tab.
@@ -446,7 +449,7 @@ api.notify("navigate", -1)
 api.notify("navigate", {
   to: "/users/456",
   replace: true, // Replace current history entry
-  force: true, // Force navigation even if path is identical
+  force: true, // Force navigation even if path is identical (useful after logout)
 })
 ```
 
@@ -480,6 +483,157 @@ export const adminPage = {
 }
 ```
 
+### 5. Route Guards (Type Composition)
+
+Route guards are implemented using **type composition** — a powerful feature of `@inglorious/store` where types can be defined as arrays of behaviors that wrap and extend each other.
+
+Guards are simply behaviors that intercept events (like `routeChange`) and can prevent navigation, redirect, or pass through to the protected page.
+
+#### Example: Authentication Guard
+
+```javascript
+// guards/require-auth.js
+export const requireAuth = (type) => ({
+  routeChange(entity, payload, api) {
+    // Only act when navigating to this specific route
+    if (payload.route !== entity.type) return
+
+    // Check authentication
+    const user = localStorage.getItem("user")
+    if (!user) {
+      // Redirect to login, preserving the intended destination
+      api.notify("navigate", {
+        to: "/login",
+        redirectTo: window.location.pathname,
+        replace: true,
+      })
+      return
+    }
+
+    // User is authenticated - pass through to the actual page handler
+    type.routeChange?.(entity, payload, api)
+  },
+})
+```
+
+#### Using Guards with Type Composition
+
+```javascript
+// store.js
+import { createStore, router } from "@inglorious/web"
+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
+  adminPage: [adminPage, requireAuth],
+}
+
+const entities = {
+  router: {
+    type: "router",
+    routes: {
+      "/login": "loginPage",
+      "/admin": "adminPage",
+    },
+  },
+  adminPage: {
+    type: "adminPage",
+  },
+  loginPage: {
+    type: "loginPage",
+  },
+}
+
+export const store = createStore({ types, entities })
+```
+
+#### How Type Composition Works
+
+When you define a type as an array like `[adminPage, requireAuth]`:
+
+1. The behaviors compose in order (left to right)
+2. Each behavior can intercept events before they reach the next behavior
+3. Guards can choose to:
+   - **Block** by returning early (not calling the next handler)
+   - **Redirect** by triggering navigation to a different route
+   - **Pass through** by calling the next behavior's handler
+
+This pattern is extremely flexible and can be used for:
+
+- **Authentication** - Check if user is logged in
+- **Authorization** - Check user roles or permissions
+- **Analytics** - Log page views
+- **Redirects** - Redirect logged-in users away from login page
+- **Loading states** - Show loading UI while checking async permissions
+- **Any cross-cutting concern** you can think of
+
+#### Multiple Guards
+
+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
+  userProfile: [userProfile, requireAuth, requireOwnership],
+}
+```
+
+Guards execute in order, so earlier guards can block navigation before later guards even run.
+
+---
+
+## Type Composition
+
+One of the most powerful features of `@inglorious/store` (and therefore `@inglorious/web`) is **type composition**. Types can be defined as arrays of behaviors that wrap each other, enabling elegant solutions to cross-cutting concerns.
+
+### Basic Composition
+
+```javascript
+const logging = (type) => ({
+  // Intercept the render method
+  render(entity, api) {
+    console.log(`Rendering ${entity.id}`)
+    return type.render(entity, api)
+  },
+
+  // Intercept any event
+  someEvent(entity, payload, api) {
+    console.log(`Event triggered on ${entity.id}`)
+    type.someEvent?.(entity, payload, api)
+  },
+})
+
+const types = {
+  // Compose the counter type with logging
+  counter: [counterBase, logging],
+}
+```
+
+### Use Cases
+
+Type composition enables elegant solutions for:
+
+- **Route guards** - Authentication, authorization, redirects
+- **Logging/debugging** - Trace renders and events
+- **Analytics** - Track user interactions
+- **Error boundaries** - Catch and handle render errors gracefully
+- **Loading states** - Show spinners during async operations
+- **Caching/memoization** - Cache expensive computations
+- **Validation** - Validate entity state before operations
+- **Any cross-cutting concern**
+
+The composition pattern keeps your code modular and reusable without introducing framework magic.
+
 ---
 
 ## Table
@@ -542,6 +696,62 @@ The table comes with a base stylesheet (`@inglorious/web/table/base.css`) and a
 
 ---
 
+## Select
+
+`@inglorious/web` includes a robust `select` type for handling dropdowns, supporting single/multi-select, filtering, and keyboard navigation.
+
+### 1. Add the `select` type
+
+Import the `select` type and its CSS, then create an entity.
+
+```javascript
+import { createStore, select } from "@inglorious/web"
+// Import base styles and theme
+import "@inglorious/web/select/base.css"
+import "@inglorious/web/select/theme.css"
+
+const types = { select }
+
+const entities = {
+  countrySelect: {
+    type: "select",
+    options: [
+      { value: "us", label: "United States" },
+      { value: "ca", label: "Canada" },
+      { value: "fr", label: "France" },
+    ],
+    // Configuration
+    isMulti: false,
+    isSearchable: true,
+    placeholder: "Select a country...",
+  },
+}
+
+const store = createStore({ types, entities })
+```
+
+### 2. Render
+
+Render it like any other entity.
+
+```javascript
+const renderApp = (api) => {
+  return html` <div class="my-form">${api.render("countrySelect")}</div> `
+}
+```
+
+### 3. State & Events
+
+The `select` entity maintains its own state:
+
+- `selectedValue`: The current value (single value or array if `isMulti: true`).
+- `isOpen`: Whether the dropdown is open.
+- `searchTerm`: Current search input.
+
+It listens to internal events like `#<id>:toggle`, `#<id>:optionSelect`, etc. You typically don't need to manually dispatch these unless you are building custom controls around it.
+
+---
+
 ## Forms
 
 `@inglorious/web` includes a small but powerful `form` type for managing form state inside your entity store. It offers:
@@ -691,6 +901,8 @@ const store = createStore({ types, entities })
 
 See `src/list.js` in the package for the implementation details and the `examples/apps/web-list` demo for a complete working example. In the demo the `productList` type extends the `list` type and provides `renderItem(item, index)` to render each visible item — see `examples/apps/web-list/src/product-list/product-list.js`.
 
+---
+
 ## API Reference
 
 **`mount(store, renderFn, element)`**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "2.5.0",
+  "version": "2.6.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",
@@ -27,7 +27,9 @@
       "import": "./src/index.js"
     },
     "./table/base.css": "./src/table/base.css",
-    "./table/theme.css": "./src/table/theme.css"
+    "./table/theme.css": "./src/table/theme.css",
+    "./select/base.css": "./src/select/base.css",
+    "./select/theme.css": "./src/select/theme.css"
   },
   "files": [
     "src",
@@ -38,7 +40,7 @@
   },
   "dependencies": {
     "lit-html": "^3.3.1",
-    "@inglorious/store": "7.1.4",
+    "@inglorious/store": "8.0.0",
     "@inglorious/utils": "3.7.0"
   },
   "devDependencies": {

package/src/form.js

@@ -26,6 +26,8 @@ import { clone, get, set } from "@inglorious/utils/data-structures/object.js"
 const NO_ITEMS_REMOVED = 0
 const ONE_ITEM_REMOVED = 1
 
+let areListenersInitialized = false
+
 /**
  * A type definition for managing form state within an entity-based system.
  * It handles initialization, field changes, validation, and submission.
@@ -37,30 +39,30 @@ export const form = {
    * Initializes the form entity by resetting it to its initial state.
    * @param {FormEntity} entity - The form entity.
    */
-  init(entity) {
-    resetForm(entity)
+  init() {
+    if (areListenersInitialized) return
 
-    document.addEventListener("click", (e) => {
-      const button = e.target.closest("button")
+    document.addEventListener("click", (event) => {
+      const button = event.target.closest("button")
 
       if (!button || button.getAttribute("type") === "submit") return
 
-      e.preventDefault()
+      event.preventDefault()
     })
 
-    document.addEventListener("submit", (e) => {
-      const form = e.target.closest("form")
+    document.addEventListener("submit", (event) => {
+      const form = event.target.closest("form")
 
       if (!form) return
-
-      e.preventDefault()
+      event.preventDefault()
     })
+
+    areListenersInitialized = true
   },
 
   /**
-   * Resets the form entity when a 'create' event matches its ID.
+   * Resets the form entity with default state.
    * @param {FormEntity} entity - The form entity.
-   * @param {string|number} entityId - The ID from the create event.
    */
   create(entity) {
     resetForm(entity)
@@ -266,6 +268,8 @@ export const form = {
   },
 }
 
+// Helper functions
+
 /**
  * Retrieves the validation error for a specific form field.
  * @param {FormEntity} form - The form entity object.

package/src/form.test.js

@@ -22,12 +22,28 @@ describe("form", () => {
   })
 
   describe("init()", () => {
+    it("should add global event listeners for click and submit", () => {
+      const spy = vi.spyOn(document, "addEventListener")
+      form.init(entity)
+      expect(spy).toHaveBeenCalledWith("click", expect.any(Function))
+      expect(spy).toHaveBeenCalledWith("submit", expect.any(Function))
+      spy.mockRestore()
+    })
+  })
+
+  describe("create()", () => {
+    it("should initialize the form", () => {
+      entity.values = {}
+      form.create(entity)
+      expect(entity.values).toEqual(entity.initialValues)
+    })
+
     it("should reset the form to its initial state", () => {
       // mess up the state first
       entity.values = {}
       entity.isPristine = false
 
-      form.init(entity)
+      form.create(entity)
 
       expect(entity.values).toEqual(entity.initialValues)
       expect(entity.values).not.toBe(entity.initialValues) // should be a clone
@@ -44,22 +60,6 @@ describe("form", () => {
         tags: [null, null],
       })
     })
-
-    it("should add global event listeners for click and submit", () => {
-      const spy = vi.spyOn(document, "addEventListener")
-      form.init(entity)
-      expect(spy).toHaveBeenCalledWith("click", expect.any(Function))
-      expect(spy).toHaveBeenCalledWith("submit", expect.any(Function))
-      spy.mockRestore()
-    })
-  })
-
-  describe("create()", () => {
-    it("should reset the form", () => {
-      entity.values = {}
-      form.create(entity)
-      expect(entity.values).toEqual(entity.initialValues)
-    })
   })
 
   describe("reset()", () => {

package/src/index.js

@@ -2,6 +2,7 @@ export { form, getFieldError, getFieldValue, isFieldTouched } from "./form.js"
 export { list } from "./list.js"
 export { mount } from "./mount.js"
 export { router } from "./router.js"
+export { select } from "./select.js"
 export { table } from "./table.js"
 export { createStore } from "@inglorious/store"
 export { createDevtools } from "@inglorious/store/client/devtools.js"

package/src/list.js

@@ -5,15 +5,26 @@ import { styleMap } from "lit-html/directives/style-map.js"
 const LIST_START = 0
 const PRETTY_INDEX = 1
 
-export const list = {
-  init(entity) {
-    resetList(entity)
-  },
+/**
+ * @typedef {import('../types/list').ListEntity} ListEntity
+ * @typedef {import('../types/mount').Api} Api
+ * @typedef {import('lit-html').TemplateResult} TemplateResult
+ */
 
+export const list = {
+  /**
+   * Initializes the list entity with default state.
+   * @param {ListEntity} entity
+   */
   create(entity) {
     resetList(entity)
   },
 
+  /**
+   * Handles the scroll event to update the visible range.
+   * @param {ListEntity} entity
+   * @param {HTMLElement} containerEl
+   */
   scroll(entity, containerEl) {
     const scrollTop = containerEl.scrollTop
     const { items, bufferSize, itemHeight, estimatedHeight, viewportHeight } =
@@ -38,6 +49,11 @@ export const list = {
     entity.visibleRange = { start, end }
   },
 
+  /**
+   * Mounts the list, measuring the first item to determine item height.
+   * @param {ListEntity} entity
+   * @param {HTMLElement} containerEl
+   */
   mount(entity, containerEl) {
     const firstItem = containerEl.querySelector("[data-index]")
     if (!firstItem) return
@@ -49,6 +65,12 @@ export const list = {
     }
   },
 
+  /**
+   * Renders the virtualized list component.
+   * @param {ListEntity} entity
+   * @param {Api} api
+   * @returns {TemplateResult}
+   */
   render(entity, api) {
     const { items, visibleRange, viewportHeight, itemHeight, estimatedHeight } =
       entity
@@ -108,11 +130,23 @@ export const list = {
     `
   },
 
-  renderItem(item, index) {
+  /**
+   * Default item renderer.
+   * @param {any} item
+   * @param {number} index
+   * @param {Api} api
+   * @returns {TemplateResult}
+   */
+  // eslint-disable-next-line no-unused-vars
+  renderItem(item, index, api) {
     return html`<div>${index + PRETTY_INDEX}. ${JSON.stringify(item)}</div>`
   },
 }
 
+/**
+ * Resets the list entity state.
+ * @param {ListEntity} entity
+ */
 function resetList(entity) {
   entity.scrollTop = 0
   entity.visibleRange ??= { start: 0, end: 20 }

package/src/list.test.js

@@ -20,9 +20,9 @@ describe("list", () => {
     }
   })
 
-  describe("init() and create()", () => {
+  describe("and create()", () => {
     it("should set default list properties on init", () => {
-      list.init(entity)
+      list.create(entity)
       expect(entity.scrollTop).toBe(0)
       expect(entity.visibleRange).toEqual({ start: 0, end: 20 })
       expect(entity.viewportHeight).toBe(600)
@@ -35,7 +35,7 @@ describe("list", () => {
       entity.viewportHeight = 800
       entity.visibleRange = { start: 10, end: 30 }
 
-      list.init(entity)
+      list.create(entity)
 
       expect(entity.viewportHeight).toBe(800)
       expect(entity.visibleRange).toEqual({ start: 10, end: 30 })
@@ -51,7 +51,7 @@ describe("list", () => {
 
   describe("scroll()", () => {
     beforeEach(() => {
-      list.init(entity)
+      list.create(entity)
     })
 
     it("should calculate visible range based on itemHeight", () => {
@@ -116,7 +116,7 @@ describe("list", () => {
 
   describe("mount()", () => {
     it("should measure and set itemHeight and update visibleRange", () => {
-      list.init(entity)
+      list.create(entity)
       const itemEl = document.createElement("div")
       vi.spyOn(itemEl, "offsetHeight", "get").mockReturnValue(40)
 
@@ -133,7 +133,7 @@ describe("list", () => {
     })
 
     it("should do nothing if no item element is found", () => {
-      list.init(entity)
+      list.create(entity)
       const originalEntity = { ...entity }
       const containerEl = {
         querySelector: vi.fn().mockReturnValue(null),
@@ -149,7 +149,7 @@ describe("list", () => {
     let api
 
     beforeEach(() => {
-      list.init(entity)
+      list.create(entity)
       api = {
         notify: vi.fn(),
         getType: vi.fn().mockReturnValue({

package/src/router.js

@@ -7,6 +7,8 @@
 const SKIP_FULL_MATCH_GROUP = 1 // .match() result at index 0 is the full string
 const REMOVE_COLON_PREFIX = 1
 
+let areListenersInitialized = false
+
 /**
  * Client-side router for entity-based systems. Handles URL changes, link interception, and browser history management.
  * @type {RouterType}
@@ -34,6 +36,9 @@ export const router = {
       })
     }
 
+    if (areListenersInitialized) return
+    areListenersInitialized = true
+
     // Listen for browser back/forward
     window.addEventListener("popstate", () => {
       const path = window.location.pathname + window.location.search

package/src/router.test.js

@@ -44,33 +44,25 @@ describe("router", () => {
   })
 
   describe("init()", () => {
-    it("should initialize with the current window.location", () => {
+    it("should initialize with the current window.location, set up a popstate listener, and set up a click listener for link interception", () => {
       vi.spyOn(window, "location", "get").mockReturnValue({
         pathname: "/users/123",
         search: "?sort=asc",
         hash: "#details",
         origin: "http://localhost:3000",
       })
+      const windowSpy = vi.spyOn(window, "addEventListener")
+      const documentSpy = vi.spyOn(document, "addEventListener")
 
-      router.init(entity, {}, api)
+      router.init(entity, undefined, api)
 
       expect(api.notify).toHaveBeenCalledWith("#router:navigate", {
         to: "/users/123?sort=asc",
         params: { id: "123" },
         replace: true,
       })
-    })
-
-    it("should set up a popstate listener", () => {
-      const spy = vi.spyOn(window, "addEventListener")
-      router.init(entity, {}, api)
-      expect(spy).toHaveBeenCalledWith("popstate", expect.any(Function))
-    })
-
-    it("should set up a click listener for link interception", () => {
-      const spy = vi.spyOn(document, "addEventListener")
-      router.init(entity, {}, api)
-      expect(spy).toHaveBeenCalledWith("click", expect.any(Function))
+      expect(windowSpy).toHaveBeenCalledWith("popstate", expect.any(Function))
+      expect(documentSpy).toHaveBeenCalledWith("click", expect.any(Function))
     })
   })
 

package/src/select/base.css

@@ -0,0 +1,52 @@
+.iw-select {
+  position: relative;
+  display: inline-block;
+  width: 100%;
+
+  .iw-select-control {
+    display: flex;
+    align-items: center;
+
+    cursor: pointer;
+    user-select: none;
+
+    .iw-select-value,
+    .iw-select-placeholder,
+    .iw-select-multi-value {
+      flex: 1;
+    }
+
+    .iw-select-multi-value {
+      display: flex;
+      flex-wrap: wrap;
+
+      .iw-select-multi-value-tag {
+        display: flex;
+        align-items: center;
+      }
+    }
+  }
+
+  .iw-select-dropdown {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    z-index: 1000;
+    display: flex;
+    flex-direction: column;
+
+    .iw-select-dropdown-search {
+      width: 100%;
+    }
+
+    .iw-select-dropdown-options {
+      .iw-select-dropdown-options-option {
+        display: flex;
+        align-items: center;
+        cursor: pointer;
+        user-select: none;
+      }
+    }
+  }
+}