@inglorious/web 2.6.0 → 2.6.1

package/README.md

@@ -216,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.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "2.6.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",
@@ -40,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,33 +39,32 @@ 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, id) {
-    if (id !== entity.id) return
+  create(entity) {
     resetForm(entity)
   },
 

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

package/src/list.js

@@ -5,16 +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
+ */
 
-  create(entity, id) {
-    if (id !== entity.id) return
+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 } =
@@ -39,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
@@ -50,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
@@ -109,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 })
@@ -43,7 +43,7 @@ describe("list", () => {
     })
 
     it("should reset the list on create", () => {
-      list.create(entity, "test-list")
+      list.create(entity)
       expect(entity.scrollTop).toBe(0)
       expect(entity.visibleRange).toEqual({ start: 0, end: 20 })
     })
@@ -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/logic.js

@@ -7,20 +7,10 @@
 
 export const logic = {
   /**
-   * Initializes the select entity with default state.
+   * Resets the select entity with default state.
    * @param {SelectEntity} entity
    */
-  init(entity) {
-    initSelect(entity)
-  },
-
-  /**
-   * Resets the select entity when a 'create' event payload matches its ID.
-   * @param {SelectEntity} entity
-   * @param {string|number} id
-   */
-  create(entity, id) {
-    if (id !== entity.id) return
+  create(entity) {
     initSelect(entity)
   },
 

package/src/select.test.js

@@ -35,9 +35,9 @@ describe("select", () => {
   })
 
   describe("logic", () => {
-    describe("init() and create()", () => {
+    describe("create()", () => {
       it("should initialize with default state", () => {
-        select.init(entity)
+        select.create(entity)
 
         expect(entity.isOpen).toBe(false)
         expect(entity.searchTerm).toBe("")
@@ -58,14 +58,14 @@ describe("select", () => {
 
       it("should initialize multi-select with empty array", () => {
         entity.isMulti = true
-        select.init(entity)
+        select.create(entity)
         expect(entity.selectedValue).toEqual([])
       })
     })
 
     describe("open() and close()", () => {
       beforeEach(() => {
-        select.init(entity)
+        select.create(entity)
       })
 
       it("open: should open the dropdown", () => {
@@ -101,7 +101,7 @@ describe("select", () => {
 
     describe("toggle()", () => {
       beforeEach(() => {
-        select.init(entity)
+        select.create(entity)
       })
 
       it("should open if closed", () => {
@@ -118,7 +118,7 @@ describe("select", () => {
 
     describe("optionSelect()", () => {
       beforeEach(() => {
-        select.init(entity)
+        select.create(entity)
       })
 
       it("should select an option in single-select mode", () => {
@@ -130,7 +130,7 @@ describe("select", () => {
 
       it("should add option in multi-select mode", () => {
         entity.isMulti = true
-        select.init(entity)
+        select.create(entity)
         entity.isOpen = true // Open dropdown first
         const option = sampleOptions[0]
         select.optionSelect(entity, option)
@@ -140,7 +140,7 @@ describe("select", () => {
 
       it("should remove option in multi-select mode if already selected", () => {
         entity.isMulti = true
-        select.init(entity)
+        select.create(entity)
         const option = sampleOptions[0]
         select.optionSelect(entity, option) // Add
         select.optionSelect(entity, option) // Remove
@@ -156,7 +156,7 @@ describe("select", () => {
 
     describe("clear()", () => {
       beforeEach(() => {
-        select.init(entity)
+        select.create(entity)
       })
 
       it("should clear selection in single-select mode", () => {
@@ -167,7 +167,7 @@ describe("select", () => {
 
       it("should clear selection in multi-select mode", () => {
         entity.isMulti = true
-        select.init(entity)
+        select.create(entity)
         entity.selectedValue = ["br", "us"]
         select.clear(entity)
         expect(entity.selectedValue).toEqual([])
@@ -183,7 +183,7 @@ describe("select", () => {
 
     describe("searchChange()", () => {
       beforeEach(() => {
-        select.init(entity)
+        select.create(entity)
       })
 
       it("should update searchTerm and filter options", () => {
@@ -211,7 +211,7 @@ describe("select", () => {
 
     describe("keyboard navigation", () => {
       beforeEach(() => {
-        select.init(entity)
+        select.create(entity)
       })
 
       it("focusNext: should move to next option", () => {

package/src/table/logic.js

@@ -7,20 +7,10 @@
 
 export const logic = {
   /**
-   * Initializes the table entity.
+   * Resets the table entity with default state.
    * @param {TableEntity} entity
    */
-  init(entity) {
-    initTable(entity)
-  },
-
-  /**
-   * Resets the table entity when a 'create' event payload matches its ID.
-   * @param {TableEntity} entity
-   * @param {string|number} id
-   */
-  create(entity, id) {
-    if (id !== entity.id) return
+  create(entity) {
     initTable(entity)
   },
 

package/src/table.test.js

@@ -61,14 +61,13 @@ describe("table", () => {
       pagination: { page: 0, pageSize: 2 },
       search: { value: "" },
     }
-    table.init(entity)
   })
 
   describe("logic", () => {
-    describe("init() and create()", () => {
+    describe("create()", () => {
       it("should initialize with default state", () => {
         const newEntity = { data: [{ id: 1, name: "Test" }] }
-        table.init(newEntity)
+        table.create(newEntity)
         expect(newEntity.sorts).toEqual([])
         expect(newEntity.filters).toEqual({})
         expect(newEntity.selection).toEqual([])
@@ -79,6 +78,10 @@ describe("table", () => {
     })
 
     describe("sortChange()", () => {
+      beforeEach(() => {
+        table.create(entity)
+      })
+
       it("should add a new sort", () => {
         table.sortChange(entity, "name")
         expect(entity.sorts).toEqual([{ column: "name", direction: "asc" }])
@@ -105,6 +108,10 @@ describe("table", () => {
     })
 
     describe("filterChange()", () => {
+      beforeEach(() => {
+        table.create(entity)
+      })
+
       it("should add a filter", () => {
         table.filterChange(entity, { columnId: "name", value: "Alice" })
         expect(entity.filters.name).toBe("Alice")
@@ -124,6 +131,10 @@ describe("table", () => {
     })
 
     describe("pagination", () => {
+      beforeEach(() => {
+        table.create(entity)
+      })
+
       it("pageNext: should go to the next page", () => {
         table.pageNext(entity)
         expect(entity.pagination.page).toBe(1)
@@ -155,6 +166,10 @@ describe("table", () => {
     })
 
     describe("selection", () => {
+      beforeEach(() => {
+        table.create(entity)
+      })
+
       it("rowToggle: should select an unselected row", () => {
         table.rowToggle(entity, 1)
         expect(entity.selection).toContain(1)
@@ -189,6 +204,10 @@ describe("table", () => {
     })
 
     describe("getters and selectors", () => {
+      beforeEach(() => {
+        table.create(entity)
+      })
+
       it("getRows: should return sorted, filtered, and paginated rows", () => {
         // Sort by age descending
         table.sortChange(entity, "age")
@@ -256,6 +275,8 @@ describe("table", () => {
           renderFooter: vi.fn(() => html`<div>Footer</div>`),
         }),
       }
+
+      table.create(entity)
     })
 
     it("render: should call sub-renderers", () => {

package/types/form.d.ts

@@ -191,20 +191,10 @@ export interface FormValidationErrorPayload {
  */
 export declare const form: {
   /**
-   * Initializes the form entity by resetting it to its initial state.
+   * Initializes the form entity with default state.
    * @param entity The form entity.
    */
-  init<T extends FormValues>(entity: FormEntity<T>): void
-
-  /**
-   * Resets the form entity when a 'create' event payload matches its ID.
-   * @param entity The form entity.
-   * @param entityId The entity ID from the create event, used to target a specific form.
-   */
-  create<T extends FormValues>(
-    entity: FormEntity<T>,
-    entityId: string | number,
-  ): void
+  create<T extends FormValues>(entity: FormEntity<T>): void
 
   /**
    * Appends an item to a field array.

package/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./form"
+export * from "./list"
 export * from "./mount"
 export * from "./router"
 export * from "./select"

package/types/list.d.ts

@@ -0,0 +1,76 @@
+import type { TemplateResult } from "lit-html"
+import type { Api } from "./mount"
+
+/**
+ * Represents the visible range of items in the list.
+ */
+export interface VisibleRange {
+  start: number
+  end: number
+}
+
+/**
+ * Represents the state of a list entity.
+ */
+export interface ListEntity<T = any> {
+  /** A unique identifier for the list entity. */
+  id: string | number
+  /** The entity type (usually 'list'). */
+  type: string
+  /** The array of items to render. */
+  items: T[]
+  /** The current scroll position of the list container. */
+  scrollTop: number
+  /** The range of items currently visible (plus buffer). */
+  visibleRange: VisibleRange
+  /** The height of the viewport in pixels. */
+  viewportHeight: number
+  /** The number of extra items to render above and below the visible range. */
+  bufferSize: number
+  /** The fixed height of each item in pixels, or null if measuring. */
+  itemHeight: number | null
+  /** The estimated height of an item, used before measurement. */
+  estimatedHeight: number
+  /** Any other custom properties. */
+  [key: string]: any
+}
+
+/**
+ * The list type implementation.
+ */
+export declare const list: {
+  /**
+   * Initializes the list entity with default state.
+   * @param entity The list entity.
+   */
+  create(entity: ListEntity): void
+
+  /**
+   * Handles the scroll event to update the visible range.
+   * @param entity The list entity.
+   * @param containerEl The scrolling container element.
+   */
+  scroll(entity: ListEntity, containerEl: HTMLElement): void
+
+  /**
+   * Mounts the list, measuring the first item to determine item height.
+   * @param entity The list entity.
+   * @param containerEl The scrolling container element.
+   */
+  mount(entity: ListEntity, containerEl: HTMLElement): void
+
+  /**
+   * Renders the virtualized list component.
+   * @param entity The list entity.
+   * @param api The store API.
+   */
+  render(entity: ListEntity, api: Api): TemplateResult
+
+  /**
+   * Default item renderer.
+   * @param item The item to render.
+   * @param index The index of the item.
+   * @param api The store API.
+   */
+  renderItem(item: any, index: number, api: Api): TemplateResult
+}

package/types/select.d.ts

@@ -61,9 +61,9 @@ export interface SelectEntity {
 export declare const select: {
   /**
    * Initializes the select entity with default state.
-   * @param entity The select entity.
+   * @param {SelectEntity} entity
    */
-  init(entity: SelectEntity): void
+  create(entity: SelectEntity): void
 
   /**
    * Renders the select component.

package/types/table.d.ts

@@ -68,17 +68,10 @@ export interface TableEntity<T = any> {
  */
 export declare const table: {
   /**
-   * Initializes the table entity.
+   * Initializes the table entity with default state.
    * @param entity The table entity.
    */
-  init(entity: TableEntity): void
-
-  /**
-   * Resets the table entity when a 'create' event payload matches its ID.
-   * @param entity The table entity.
-   * @param id The ID of the entity to create/reset.
-   */
-  create(entity: TableEntity, id: string): void
+  create(entity: TableEntity): void
 
   /**
    * Toggles sorting for a specific column.