@inglorious/web 2.5.0 → 2.6.0

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:
 
 ---
 
@@ -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.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",
@@ -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",

package/src/form.js

@@ -62,7 +62,8 @@ export const form = {
    * @param {FormEntity} entity - The form entity.
    * @param {string|number} entityId - The ID from the create event.
    */
-  create(entity) {
+  create(entity, id) {
+    if (id !== entity.id) return
     resetForm(entity)
   },
 
@@ -266,6 +267,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

@@ -57,14 +57,14 @@ describe("form", () => {
   describe("create()", () => {
     it("should reset the form", () => {
       entity.values = {}
-      form.create(entity)
+      form.create(entity, "test-form")
       expect(entity.values).toEqual(entity.initialValues)
     })
   })
 
   describe("reset()", () => {
     it("should reset the form to its initial state", () => {
-      form.create(entity)
+      form.create(entity, "test-form")
       entity.values.name = "Jane Doe"
       entity.isPristine = false
 
@@ -77,7 +77,7 @@ describe("form", () => {
 
   describe("fieldChange()", () => {
     beforeEach(() => {
-      form.create(entity)
+      form.create(entity, "test-form")
     })
 
     it("should update a field's value, mark it as touched, and set form to dirty", () => {
@@ -124,7 +124,7 @@ describe("form", () => {
 
   describe("fieldBlur()", () => {
     beforeEach(() => {
-      form.create(entity)
+      form.create(entity, "test-form")
     })
 
     it("should mark a field as touched", () => {
@@ -144,7 +144,7 @@ describe("form", () => {
 
   describe("field array operations", () => {
     beforeEach(() => {
-      form.create(entity)
+      form.create(entity, "test-form")
     })
 
     it("fieldArrayAppend: should append a value and metadata", () => {
@@ -198,7 +198,7 @@ describe("form", () => {
 
   describe("validate()", () => {
     beforeEach(() => {
-      form.create(entity)
+      form.create(entity, "test-form")
     })
 
     it("should set errors and isValid based on the validation function", () => {
@@ -231,7 +231,7 @@ describe("form", () => {
     let api
 
     beforeEach(() => {
-      form.create(entity)
+      form.create(entity, "test-form")
       api = { notify: vi.fn() }
     })
 
@@ -271,7 +271,7 @@ describe("form", () => {
 
   describe("validationComplete()", () => {
     it("should update form state after async validation", () => {
-      form.create(entity)
+      form.create(entity, "test-form")
       entity.isValidating = true
       const errors = { name: "Error" }
 
@@ -285,7 +285,7 @@ describe("form", () => {
 
   describe("validationError()", () => {
     it("should update form state after an async validation error", () => {
-      form.create(entity)
+      form.create(entity, "test-form")
       entity.isValidating = true
 
       form.validationError(entity, { error: "Network Error" })

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

@@ -10,7 +10,8 @@ export const list = {
     resetList(entity)
   },
 
-  create(entity) {
+  create(entity, id) {
+    if (id !== entity.id) return
     resetList(entity)
   },
 

package/src/list.test.js

@@ -43,7 +43,7 @@ describe("list", () => {
     })
 
     it("should reset the list on create", () => {
-      list.create(entity)
+      list.create(entity, "test-list")
       expect(entity.scrollTop).toBe(0)
       expect(entity.visibleRange).toEqual({ start: 0, end: 20 })
     })

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;
+      }
+    }
+  }
+}