@inglorious/web 2.2.1 → 2.2.2

package/README.md

@@ -410,30 +410,6 @@ 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. This allows you to define rendering logic alongside an entity's other behaviors.
 
-**`api.select(selectorFn)`**
-
-Selects a slice of the application state and returns a reactive getter function. This is useful for creating components that only depend on a small part of the state, avoiding unnecessary re-renders.
-
-The `selectorFn` receives the `api` and should return a value. The `select` method returns a getter function that you call to get the latest value. This function also has an `unsubscribe` property.
-
-**Parameters:**
-
-- `selectorFn(api)` (required): A function that takes the `api` and returns a slice of the state.
-
-**Returns:**
-
-- `() => T`: A reactive getter function. It also has an `unsubscribe` method attached.
-
-**Example:**
-
-While `mount` re-renders the entire application on any state change, `api.select` can be used inside a component to react only to specific changes. This is an advanced pattern for performance optimization.
-
-```javascript
-// Inside a component's render method
-const getUser = api.select((api) => api.getEntity("user-1"))
-const user = getUser() // Call the getter to get the value
-```
-
 ### Re-exported `lit-html` Utilities
 
 For convenience, `@inglorious/web` re-exports the most common utilities from `@inglorious/store` and `lit-html`, so you only need one import.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "2.2.1",
+  "version": "2.2.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",
@@ -45,7 +45,7 @@
     "prettier": "^3.6.2",
     "vite": "^7.1.3",
     "vitest": "^4.0.15",
-    "@inglorious/eslint-config": "1.1.0"
+    "@inglorious/eslint-config": "1.1.1"
   },
   "engines": {
     "node": ">= 22"

package/src/form.js

@@ -291,10 +291,10 @@ export function getFieldValue(form, path, defaultValue) {
  * Checks if a specific form field has been touched (i.e., has received a blur event).
  * @param {FormEntity} form - The form entity object.
  * @param {string} path - The dot-separated path to the field (e.g., 'user.name').
- * @returns {boolean|undefined} `true` if the field has been touched, otherwise `false` or `undefined`.
+ * @returns {boolean} `true` if the field has been touched, otherwise `false`.
  */
 export function isFieldTouched(form, path) {
-  return get(form.touched, path)
+  return Boolean(get(form.touched, path))
 }
 
 // Private helper functions

package/src/form.test.js

@@ -0,0 +1,372 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+import { form, getFieldError, getFieldValue, isFieldTouched } from "./form.js"
+
+describe("form", () => {
+  let entity
+
+  beforeEach(() => {
+    entity = {
+      id: "test-form",
+      initialValues: {
+        name: "John Doe",
+        contact: {
+          email: "john.doe@example.com",
+        },
+        tags: ["a", "b"],
+      },
+    }
+  })
+
+  describe("init()", () => {
+    it("should reset the form to its initial state", () => {
+      // mess up the state first
+      entity.values = {}
+      entity.isPristine = false
+
+      form.init(entity)
+
+      expect(entity.values).toEqual(entity.initialValues)
+      expect(entity.values).not.toBe(entity.initialValues) // should be a clone
+      expect(entity.isPristine).toBe(true)
+      expect(entity.isValid).toBe(true)
+      expect(entity.errors).toEqual({
+        name: null,
+        contact: { email: null },
+        tags: [null, null],
+      })
+      expect(entity.touched).toEqual({
+        name: null,
+        contact: { email: null },
+        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()", () => {
+    it("should reset the form to its initial state", () => {
+      form.create(entity)
+      entity.values.name = "Jane Doe"
+      entity.isPristine = false
+
+      form.reset(entity)
+
+      expect(entity.values).toEqual(entity.initialValues)
+      expect(entity.isPristine).toBe(true)
+    })
+  })
+
+  describe("fieldChange()", () => {
+    beforeEach(() => {
+      form.create(entity)
+    })
+
+    it("should update a field's value, mark it as touched, and set form to dirty", () => {
+      form.fieldChange(entity, { path: "name", value: "Jane Doe" })
+
+      expect(entity.values.name).toBe("Jane Doe")
+      expect(entity.touched.name).toBe(true)
+      expect(entity.isPristine).toBe(false)
+    })
+
+    it("should update a nested field's value", () => {
+      form.fieldChange(entity, {
+        path: "contact.email",
+        value: "jane.doe@example.com",
+      })
+
+      expect(entity.values.contact.email).toBe("jane.doe@example.com")
+      expect(entity.touched.contact.email).toBe(true)
+    })
+
+    it("should validate the field if a validate function is provided", () => {
+      const validate = (value) => (value.length < 10 ? "Too short" : null)
+      form.fieldChange(entity, { path: "name", value: "Jane", validate })
+
+      expect(entity.errors.name).toBe("Too short")
+      expect(entity.isValid).toBe(false)
+    })
+
+    it("should clear a field's error when it becomes valid", () => {
+      const validate = (value) => (value.length < 10 ? "Too short" : null)
+      form.fieldChange(entity, { path: "name", value: "Jane", validate })
+      expect(entity.isValid).toBe(false)
+
+      form.fieldChange(entity, {
+        path: "name",
+        value: "Jane Doe The Great",
+        validate,
+      })
+
+      expect(entity.errors.name).toBe(null)
+      expect(entity.isValid).toBe(true)
+    })
+  })
+
+  describe("fieldBlur()", () => {
+    beforeEach(() => {
+      form.create(entity)
+    })
+
+    it("should mark a field as touched", () => {
+      form.fieldBlur(entity, { path: "name" })
+      expect(entity.touched.name).toBe(true)
+    })
+
+    it("should validate the field if a validate function is provided", () => {
+      const validate = (value) =>
+        value === "John Doe" ? "Cannot be John" : null
+      form.fieldBlur(entity, { path: "name", validate })
+
+      expect(entity.errors.name).toBe("Cannot be John")
+      expect(entity.isValid).toBe(false)
+    })
+  })
+
+  describe("field array operations", () => {
+    beforeEach(() => {
+      form.create(entity)
+    })
+
+    it("fieldArrayAppend: should append a value and metadata", () => {
+      form.fieldArrayAppend(entity, { path: "tags", value: "c" })
+
+      expect(entity.values.tags).toEqual(["a", "b", "c"])
+      expect(entity.errors.tags).toEqual([null, null, null])
+      expect(entity.touched.tags).toEqual([null, null, null])
+      expect(entity.isPristine).toBe(false)
+    })
+
+    it("fieldArrayRemove: should remove a value and metadata at an index", () => {
+      form.fieldArrayRemove(entity, { path: "tags", index: 0 })
+
+      expect(entity.values.tags).toEqual(["b"])
+      expect(entity.errors.tags).toEqual([null])
+      expect(entity.touched.tags).toEqual([null])
+      expect(entity.isPristine).toBe(false)
+    })
+
+    it("fieldArrayInsert: should insert a value and metadata at an index", () => {
+      form.fieldArrayInsert(entity, { path: "tags", index: 1, value: "c" })
+
+      expect(entity.values.tags).toEqual(["a", "c", "b"])
+      expect(entity.errors.tags).toEqual([null, null, null])
+      expect(entity.touched.tags).toEqual([null, null, null])
+      expect(entity.isPristine).toBe(false)
+    })
+
+    it("fieldArrayMove: should move a value and metadata", () => {
+      entity.errors.tags[0] = "Error on A"
+      entity.touched.tags[0] = true
+
+      form.fieldArrayMove(entity, { path: "tags", fromIndex: 0, toIndex: 1 })
+
+      expect(entity.values.tags).toEqual(["b", "a"])
+      expect(entity.errors.tags).toEqual([null, "Error on A"])
+      expect(entity.touched.tags).toEqual([null, true])
+      expect(entity.isPristine).toBe(false)
+    })
+
+    it("fieldArray operations should warn if path is not an array", () => {
+      const spy = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+      form.fieldArrayAppend(entity, { path: "name", value: "c" })
+      expect(spy).toHaveBeenCalledWith("Field at path 'name' is not an array")
+
+      spy.mockRestore()
+    })
+  })
+
+  describe("validate()", () => {
+    beforeEach(() => {
+      form.create(entity)
+    })
+
+    it("should set errors and isValid based on the validation function", () => {
+      const validate = (values) => {
+        const errors = {}
+        if (values.name !== "Jane Doe") {
+          errors.name = "Name must be Jane Doe"
+        }
+        return errors
+      }
+
+      form.validate(entity, { validate })
+
+      expect(entity.errors.name).toBe("Name must be Jane Doe")
+      expect(entity.isValid).toBe(false)
+    })
+
+    it("should set isValid to true if there are no errors", () => {
+      const validate = () => ({})
+
+      entity.isValid = false
+      form.validate(entity, { validate })
+
+      expect(entity.errors).toEqual({})
+      expect(entity.isValid).toBe(true)
+    })
+  })
+
+  describe("validateAsync()", () => {
+    let api
+
+    beforeEach(() => {
+      form.create(entity)
+      api = { notify: vi.fn() }
+    })
+
+    it("should set isValidating to true and call the validation function", async () => {
+      const validate = vi.fn().mockResolvedValue({})
+      await form.validateAsync(entity, { validate }, api)
+      expect(entity.isValidating).toBe(true)
+      expect(validate).toHaveBeenCalledWith(entity.values)
+    })
+
+    it("should notify 'validationComplete' on successful validation", async () => {
+      const errors = { name: "Required" }
+      const validate = async () => errors
+      await form.validateAsync(entity, { validate }, api)
+
+      expect(api.notify).toHaveBeenCalledWith(
+        `#${entity.id}:validationComplete`,
+        {
+          errors,
+          isValid: false,
+        },
+      )
+    })
+
+    it("should notify 'validationError' on validation failure", async () => {
+      const error = new Error("Validation failed")
+      const validate = async () => {
+        throw error
+      }
+      await form.validateAsync(entity, { validate }, api)
+
+      expect(api.notify).toHaveBeenCalledWith(`#${entity.id}:validationError`, {
+        error: "Validation failed",
+      })
+    })
+  })
+
+  describe("validationComplete()", () => {
+    it("should update form state after async validation", () => {
+      form.create(entity)
+      entity.isValidating = true
+      const errors = { name: "Error" }
+
+      form.validationComplete(entity, { errors, isValid: false })
+
+      expect(entity.isValidating).toBe(false)
+      expect(entity.errors).toBe(errors)
+      expect(entity.isValid).toBe(false)
+    })
+  })
+
+  describe("validationError()", () => {
+    it("should update form state after an async validation error", () => {
+      form.create(entity)
+      entity.isValidating = true
+
+      form.validationError(entity, { error: "Network Error" })
+
+      expect(entity.isValidating).toBe(false)
+      expect(entity.submitError).toBe("Network Error")
+    })
+  })
+})
+
+describe("form helpers", () => {
+  let testForm
+
+  beforeEach(() => {
+    testForm = {
+      values: {
+        user: { name: "Alex" },
+        tags: ["one", "two"],
+      },
+      errors: {
+        user: { name: "Too short" },
+        tags: [null, "Invalid tag"],
+      },
+      touched: {
+        user: { name: true },
+        tags: [true, false],
+      },
+    }
+  })
+
+  describe("getFieldValue()", () => {
+    it("should return the value of a field at a given path", () => {
+      expect(getFieldValue(testForm, "user.name")).toBe("Alex")
+    })
+
+    it("should return an array value", () => {
+      expect(getFieldValue(testForm, "tags")).toEqual(["one", "two"])
+    })
+
+    it("should return a default value if path does not exist", () => {
+      expect(getFieldValue(testForm, "user.age", 30)).toBe(30)
+    })
+
+    it("should return undefined if path does not exist and no default is provided", () => {
+      expect(getFieldValue(testForm, "user.age")).toBeUndefined()
+    })
+  })
+
+  describe("getFieldError()", () => {
+    it("should return the error of a field at a given path", () => {
+      expect(getFieldError(testForm, "user.name")).toBe("Too short")
+    })
+
+    it("should return the error of a field in an array", () => {
+      expect(getFieldError(testForm, "tags.1")).toBe("Invalid tag")
+    })
+
+    it("should return null for a valid field in an array", () => {
+      expect(getFieldError(testForm, "tags.0")).toBeNull()
+    })
+
+    it("should return undefined if path does not exist", () => {
+      expect(getFieldError(testForm, "user.age")).toBe(undefined)
+    })
+  })
+
+  describe("isFieldTouched()", () => {
+    it("should return true if a field has been touched", () => {
+      expect(isFieldTouched(testForm, "user.name")).toBe(true)
+    })
+
+    it("should return true for a touched field in an array", () => {
+      expect(isFieldTouched(testForm, "tags.0")).toBe(true)
+    })
+
+    it("should return false for an untouched field in an array", () => {
+      expect(isFieldTouched(testForm, "tags.1")).toBe(false)
+    })
+
+    it("should return false if path does not exist", () => {
+      expect(isFieldTouched(testForm, "user.age")).toBe(false)
+    })
+  })
+})

package/src/list.test.js

@@ -0,0 +1,228 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { html } from "lit-html"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+import { list } from "./list.js"
+
+describe("list", () => {
+  let entity
+
+  beforeEach(() => {
+    entity = {
+      id: "test-list",
+      type: "test-item-type",
+      items: Array.from({ length: 100 }, (_, i) => ({
+        id: i,
+        name: `Item ${i}`,
+      })),
+    }
+  })
+
+  describe("init() and create()", () => {
+    it("should set default list properties on init", () => {
+      list.init(entity)
+      expect(entity.scrollTop).toBe(0)
+      expect(entity.visibleRange).toEqual({ start: 0, end: 20 })
+      expect(entity.viewportHeight).toBe(600)
+      expect(entity.bufferSize).toBe(5)
+      expect(entity.itemHeight).toBeNull()
+      expect(entity.estimatedHeight).toBe(50)
+    })
+
+    it("should not overwrite existing properties on init (except scrollTop)", () => {
+      entity.viewportHeight = 800
+      entity.visibleRange = { start: 10, end: 30 }
+
+      list.init(entity)
+
+      expect(entity.viewportHeight).toBe(800)
+      expect(entity.visibleRange).toEqual({ start: 10, end: 30 })
+      expect(entity.scrollTop).toBe(0) // scrollTop is always reset
+    })
+
+    it("should reset the list on create", () => {
+      list.create(entity)
+      expect(entity.scrollTop).toBe(0)
+      expect(entity.visibleRange).toEqual({ start: 0, end: 20 })
+    })
+  })
+
+  describe("scroll()", () => {
+    beforeEach(() => {
+      list.init(entity)
+    })
+
+    it("should calculate visible range based on itemHeight", () => {
+      entity.itemHeight = 20
+      const containerEl = { scrollTop: 200 } // 10 items down
+
+      list.scroll(entity, containerEl)
+
+      // start = floor(200 / 20) - 5 = 10 - 5 = 5
+      // visibleCount = ceil(600 / 20) = 30
+      // end = min(5 + 30 + 5, 100) = 40
+      expect(entity.visibleRange).toEqual({ start: 5, end: 40 })
+      expect(entity.scrollTop).toBe(200)
+    })
+
+    it("should calculate visible range based on estimatedHeight if itemHeight is null", () => {
+      entity.estimatedHeight = 50
+      const containerEl = { scrollTop: 500 } // 10 items down
+
+      list.scroll(entity, containerEl)
+
+      // start = floor(500 / 50) - 5 = 10 - 5 = 5
+      // visibleCount = ceil(600 / 50) = 12
+      // end = min(5 + 12 + 5, 100) = 22
+      expect(entity.visibleRange).toEqual({ start: 5, end: 22 })
+    })
+
+    it("should not update if the visible range has not changed", () => {
+      entity.itemHeight = 20
+      entity.visibleRange = { start: 5, end: 40 }
+      const originalRange = { ...entity.visibleRange }
+
+      const containerEl = { scrollTop: 201 } // Still within the same range calculation
+      list.scroll(entity, containerEl)
+
+      expect(entity.visibleRange).toEqual(originalRange) // Should not have changed
+    })
+
+    it("should handle scrolling to the top", () => {
+      entity.itemHeight = 20
+      const containerEl = { scrollTop: 0 }
+
+      list.scroll(entity, containerEl)
+
+      // start = max(0, floor(0/20) - 5) = 0
+      // end = min(0 + 30 + 5, 100) = 35
+      expect(entity.visibleRange).toEqual({ start: 0, end: 35 })
+    })
+
+    it("should handle scrolling near the bottom", () => {
+      entity.itemHeight = 20
+      const containerEl = { scrollTop: 1900 } // 95 items down
+
+      list.scroll(entity, containerEl)
+
+      // start = floor(1900 / 20) - 5 = 95 - 5 = 90
+      // visibleCount = 30
+      // end = min(90 + 30 + 5, 100) = 100
+      expect(entity.visibleRange).toEqual({ start: 90, end: 100 })
+    })
+  })
+
+  describe("mount()", () => {
+    it("should measure and set itemHeight and update visibleRange", () => {
+      list.init(entity)
+      const itemEl = document.createElement("div")
+      vi.spyOn(itemEl, "offsetHeight", "get").mockReturnValue(40)
+
+      const containerEl = {
+        querySelector: vi.fn().mockReturnValue(itemEl),
+      }
+
+      list.mount(entity, containerEl)
+
+      expect(containerEl.querySelector).toHaveBeenCalledWith("[data-index]")
+      expect(entity.itemHeight).toBe(40)
+      // end = ceil(600 / 40) = 15
+      expect(entity.visibleRange).toEqual({ start: 0, end: 15 })
+    })
+
+    it("should do nothing if no item element is found", () => {
+      list.init(entity)
+      const originalEntity = { ...entity }
+      const containerEl = {
+        querySelector: vi.fn().mockReturnValue(null),
+      }
+
+      list.mount(entity, containerEl)
+
+      expect(entity).toEqual(originalEntity)
+    })
+  })
+
+  describe("render()", () => {
+    let api
+
+    beforeEach(() => {
+      list.init(entity)
+      api = {
+        notify: vi.fn(),
+        getType: vi.fn().mockReturnValue({
+          renderItem: (item, index) => html`<div>${index}: ${item.name}</div>`,
+        }),
+      }
+    })
+
+    it("should return a lit-html TemplateResult", () => {
+      const result = list.render(entity, api)
+      // Duck-typing for TemplateResult, as it's not a public class
+      expect(result).toHaveProperty("strings")
+      expect(result).toHaveProperty("values")
+    })
+
+    it("should warn and return empty if items are missing", () => {
+      const spy = vi.spyOn(console, "warn").mockImplementation(() => {})
+      delete entity.items
+      const result = list.render(entity, api)
+      expect(spy).toHaveBeenCalledWith(`list entity ${entity.id} needs 'items'`)
+      expect(result.strings.join("").trim()).toBe("")
+      spy.mockRestore()
+    })
+
+    it("should warn and return empty if type.renderItem is missing", () => {
+      const spy = vi.spyOn(console, "warn").mockImplementation(() => {})
+      api.getType.mockReturnValue({}) // No renderItem
+      const result = list.render(entity, api)
+      expect(spy).toHaveBeenCalledWith(
+        `type ${entity.type} needs 'renderItem' method`,
+      )
+      expect(result.strings.join("").trim()).toBe("")
+      spy.mockRestore()
+    })
+
+    it("should render only the visible items", () => {
+      entity.itemHeight = 50
+      entity.visibleRange = { start: 10, end: 15 } // 5 visible items
+
+      const result = list.render(entity, api)
+      const renderedItems = result.values.find(Array.isArray)
+
+      expect(renderedItems).toHaveLength(5) // 5 visible items
+      // Check if the first rendered item is indeed item 10
+      const innerTemplate = renderedItems[0].values[2]
+      const renderedText = `${innerTemplate.values[0]}: ${innerTemplate.values[1]}`
+      expect(renderedText).toBe("10: Item 10")
+    })
+
+    it("should calculate total height correctly", () => {
+      entity.itemHeight = 40
+      const result = list.render(entity, api)
+      // The styleMap for the inner div is at result.values[3].values[0]
+      const styleValue = result.values[3].values[0]
+      const expectedHeight = 100 * 40 // items.length * itemHeight
+      expect(styleValue.height).toBe(`${expectedHeight}px`)
+    })
+  })
+
+  describe("renderItem()", () => {
+    it("should render a default item view", () => {
+      const item = { id: 1, value: "test" }
+      const result = list.renderItem(item, 5)
+      // Duck-typing for TemplateResult
+      expect(result).toHaveProperty("strings")
+      expect(result).toHaveProperty("values")
+      const fullText =
+        result.strings[0] +
+        result.values[0] +
+        result.strings[1] +
+        result.values[1] +
+        result.strings[2]
+      expect(fullText).toBe(`<div>6. ${JSON.stringify(item)}</div>`)
+    })
+  })
+})