@inglorious/web 2.1.1 → 2.2.0

package/README.md

@@ -404,9 +404,34 @@ Connects a store to a `lit-html` template and renders it into a DOM element. It
 
 ### The `api` Object
 
-The `renderFn` receives a powerful `api` object that contains all methods from the store's API (`getEntities`, `getEntity`, `notify`, etc.) plus a special `render(id)` method.
+The `renderFn` receives a powerful `api` object that contains all methods from the store's API (`getEntities`, `getEntity`, `notify`, etc.) plus special methods for the web package.
 
-This `render(id)` 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.render(id, options?)`**
+
+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 object. 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 an object with a `value` property and an `unsubscribe` function.
+
+**Parameters:**
+
+- `selectorFn(api)` (required): A function that takes the `api` and returns a slice of the state.
+
+**Returns:**
+
+- `{ value, unsubscribe }`: A reactive result object.
+
+**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 { value: user } = api.select((api) => api.getEntity("user-1"))
+```
 
 ### Re-exported `lit-html` Utilities
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "2.1.1",
+  "version": "2.2.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",
@@ -44,6 +44,7 @@
   "devDependencies": {
     "prettier": "^3.6.2",
     "vite": "^7.1.3",
+    "vitest": "^4.0.15",
     "@inglorious/eslint-config": "1.1.0"
   },
   "engines": {
@@ -51,6 +52,8 @@
   },
   "scripts": {
     "format": "prettier --write '**/*.{js,jsx}'",
-    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0"
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
+    "test:watch": "vitest",
+    "test": "vitest run"
   }
 }

package/src/index.js

@@ -12,3 +12,4 @@ 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 { when } from "lit-html/directives/when.js"

package/src/mount.js

@@ -8,41 +8,75 @@ import { html, render } from "lit-html"
  * @returns {() => void} An unsubscribe function
  */
 export function mount(store, renderFn, element) {
-  const api = {
-    ...store._api,
-
-    /** @param {string} id */
-    render(id, options = {}) {
-      const entity = api.getEntity(id)
-
-      if (!entity) {
-        const { allowType } = options
-        if (!allowType) {
-          return ""
-        }
-
-        // No entity with this ID, try static type
-        const type = api.getType(id)
-        if (!type?.render) {
-          console.warn(`No entity or type found: ${id}`)
-          return html`<div>Not found: ${id}</div>`
-        }
-        return type.render(api)
-      }
+  const api = { ...store._api }
+  api.select = createReactiveSelector(api, store)
+  api.render = createRender(api)
 
-      // Entity exists, render it
-      const type = api.getType(entity.type)
-      if (!type?.render) {
-        console.warn(`No render function for type: ${entity.type}`)
-        return html`<div>No renderer for ${entity.type}</div>`
+  const unsubscribe = store.subscribe(() => render(renderFn(api), element))
+  store.notify("init")
+
+  return unsubscribe
+}
+
+/**
+ * Creates a reactive selector function for the mount API.
+ * @param {import('../types/mount').Api} api - The mount API.
+ * @param {import('@inglorious/store').Store} store - The application state store.
+ * @returns {import('../types/mount').Api['select']} A `select` function that can be used to get a reactive slice of the state.
+ * @private
+ */
+function createReactiveSelector(api, store) {
+  return function select(selectorFn) {
+    let current = selectorFn(api)
+
+    const unsubscribe = store.subscribe(() => {
+      const next = selectorFn(api)
+      if (next !== current) {
+        current = next
       }
+    })
 
-      return type.render(entity, api)
-    },
+    return {
+      get value() {
+        return current
+      },
+      unsubscribe,
+    }
   }
+}
 
-  const unsubscribe = store.subscribe(() => render(renderFn(api), element))
-  store.notify("init")
+/**
+ * Creates a render function for the mount API.
+ * @param {import('../types/mount').Api} api - The mount API.
+ * @returns {import('../types/mount').Api['render']} A `render` function that can render an entity or a type by its ID.
+ * @private
+ */
+function createRender(api) {
+  return function (id, options = {}) {
+    const entity = api.getEntity(id)
 
-  return unsubscribe
+    if (!entity) {
+      const { allowType } = options
+      if (!allowType) {
+        return ""
+      }
+
+      // No entity with this ID, try static type
+      const type = api.getType(id)
+      if (!type?.render) {
+        console.warn(`No entity or type found: ${id}`)
+        return html`<div>Not found: ${id}</div>`
+      }
+      return type.render(api)
+    }
+
+    // Entity exists, render it
+    const type = api.getType(entity.type)
+    if (!type?.render) {
+      console.warn(`No render function for type: ${entity.type}`)
+      return html`<div>No renderer for ${entity.type}</div>`
+    }
+
+    return type.render(entity, api)
+  }
 }

package/src/mount.test.js

@@ -0,0 +1,255 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { createStore } from "@inglorious/store"
+import { html } from "lit-html" // Only html is needed for templates, render is handled by mount
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import { mount } from "./mount.js"
+
+let rootElement
+
+beforeEach(() => {
+  // Create a fresh DOM element for each test
+  rootElement = document.createElement("div")
+  document.body.appendChild(rootElement)
+  // Spy on console.warn to check for warnings without polluting test output
+  vi.spyOn(console, "warn").mockImplementation(() => {})
+})
+
+afterEach(() => {
+  // Clean up the DOM element after each test
+  document.body.removeChild(rootElement)
+  // Restore console.warn to its original implementation
+  vi.restoreAllMocks()
+})
+
+// Helper function to create a store with some common entities and types for testing
+function setupStore(entitiesOverride = {}, typesOverride = {}) {
+  return createStore({
+    // Pass 'entities' as a top-level property to createStore
+    entities: {
+      "player-1": {
+        id: "player-1",
+        type: "player",
+        name: "Player One",
+        score: 0,
+      },
+      "enemy-1": { id: "enemy-1", type: "enemy", health: 100 },
+      ...entitiesOverride,
+    },
+    // Pass 'types' as a top-level property to createStore
+    types: {
+      player: {
+        render: (entity) =>
+          html`<span>Player: ${entity.name}, Score: ${entity.score}</span>`,
+        incrementScore: (entity) => {
+          entity.score++
+        },
+      },
+      enemy: {
+        render: (entity) => html`<span>Enemy: ${entity.health} HP</span>`,
+        takeDamage: (entity, amount) => {
+          entity.health -= amount
+        },
+      },
+      simpleType: {
+        render: () => html`<span>Simple Type Rendered</span>`,
+      },
+      typeWithoutRender: {
+        /* no render function */
+      },
+      ...typesOverride,
+    },
+  })
+}
+
+describe("mount", () => {
+  it("should render the initial state into the element", () => {
+    const store = setupStore()
+    const renderFn = (api) =>
+      html`<div>Hello, ${api.getEntity("player-1").name}!</div>`
+    mount(store, renderFn, rootElement)
+
+    expect(rootElement.textContent).toBe("Hello, Player One!")
+  })
+
+  it("should re-render when the store state changes", async () => {
+    const store = setupStore()
+    const renderFn = (api) =>
+      html`<div>Score: ${api.getEntity("player-1").score}</div>`
+    mount(store, renderFn, rootElement)
+
+    expect(rootElement.textContent).toBe("Score: 0")
+
+    store.notify("incrementScore", "player-1")
+    // lit-html renders asynchronously, so we need to wait for the next microtask
+    await Promise.resolve()
+
+    expect(rootElement.textContent).toBe("Score: 1")
+  })
+
+  it("should stop re-rendering after unsubscribe is called", async () => {
+    const store = setupStore()
+    const renderFn = (api) =>
+      html`<div>Score: ${api.getEntity("player-1").score}</div>`
+    const unsubscribe = mount(store, renderFn, rootElement)
+
+    expect(rootElement.textContent).toBe("Score: 0")
+
+    unsubscribe()
+    store.notify("incrementScore", "player-1")
+    await Promise.resolve() // Wait for potential re-render
+
+    // The score should still be 0 in the DOM because unsubscribe was called
+    expect(rootElement.textContent).toBe("Score: 0")
+    expect(rootElement.textContent).not.toBe("Score: 1")
+  })
+
+  describe("api.select", () => {
+    let capturedSelectResult // Used to capture the ReactiveSelectorResult instance across renders
+
+    it("should return the initial selected value", () => {
+      const store = setupStore()
+      const renderFn = (api) => {
+        capturedSelectResult = api.select(
+          (api) => api.getEntity("player-1").score,
+        )
+        return html`<div>Selected: ${capturedSelectResult.value}</div>`
+      }
+      mount(store, renderFn, rootElement)
+
+      expect(capturedSelectResult.value).toBe(0)
+      expect(rootElement.textContent).toBe("Selected: 0")
+    })
+
+    it("should update the selected value when the relevant state changes", async () => {
+      const store = setupStore()
+      const renderFn = (api) => {
+        capturedSelectResult = api.select(
+          (api) => api.getEntity("player-1").score,
+        )
+        return html`<div>Selected: ${capturedSelectResult.value}</div>`
+      }
+      mount(store, renderFn, rootElement)
+
+      expect(capturedSelectResult.value).toBe(0)
+
+      store.notify("incrementScore", "player-1")
+      await Promise.resolve() // Wait for store subscription to trigger and update `current` in select, and for lit-html to render
+
+      expect(capturedSelectResult.value).toBe(1)
+      expect(rootElement.textContent).toBe("Selected: 1")
+    })
+
+    it("should not update the selected value when unrelated state changes", async () => {
+      const store = setupStore()
+      const renderFn = (api) => {
+        capturedSelectResult = api.select(
+          (api) => api.getEntity("player-1").score,
+        )
+        return html`<div>Selected: ${capturedSelectResult.value}</div>`
+      }
+      mount(store, renderFn, rootElement)
+
+      expect(capturedSelectResult.value).toBe(0)
+
+      store.notify("takeDamage", "enemy-1", 10) // This changes enemy health, not player score
+      await Promise.resolve()
+
+      expect(capturedSelectResult.value).toBe(0) // Should remain 0
+      expect(rootElement.textContent).toBe("Selected: 0") // DOM also remains 0
+    })
+
+    it("should stop updating after api.select unsubscribe is called", async () => {
+      const store = setupStore()
+      let initialSelectResult
+      const renderFn = (api) => {
+        // Capture the select result only on the first render to test its specific unsubscribe
+        if (!initialSelectResult) {
+          initialSelectResult = api.select(
+            (api) => api.getEntity("player-1").score,
+          )
+        }
+        return html`<div>Selected: ${initialSelectResult.value}</div>`
+      }
+      mount(store, renderFn, rootElement)
+
+      expect(initialSelectResult.value).toBe(0)
+
+      initialSelectResult.unsubscribe() // Unsubscribe the reactive selector's internal listener
+      store.notify("incrementScore", "player-1")
+      await Promise.resolve() // Wait for store subscription to trigger and for lit-html to render
+
+      // The main mount subscription still triggers renderFn, but the `initialSelectResult.value`
+      // should *not* have updated because its internal listener was unsubscribed.
+      expect(initialSelectResult.value).toBe(0) // Should remain 0
+      expect(rootElement.textContent).toBe("Selected: 0")
+      expect(rootElement.textContent).not.toBe("Selected: 1")
+    })
+  })
+
+  describe("api.render", () => {
+    it("should render an entity by its ID", async () => {
+      const store = setupStore()
+      const renderFn = (api) => html`<div>${api.render("player-1")}</div>`
+      mount(store, renderFn, rootElement)
+      await Promise.resolve()
+
+      expect(rootElement.textContent).toBe("Player: Player One, Score: 0")
+    })
+
+    it("should render a type by its ID when allowType is true", async () => {
+      const store = setupStore()
+      const renderFn = (api) =>
+        html`<div>${api.render("simpleType", { allowType: true })}</div>`
+      mount(store, renderFn, rootElement)
+      await Promise.resolve()
+
+      expect(rootElement.textContent).toBe("Simple Type Rendered")
+    })
+
+    it("should return an empty string for a non-existent entity/type without allowType", async () => {
+      const store = setupStore()
+      const renderFn = (api) =>
+        html`<div>${api.render("non-existent-id")}</div>`
+      mount(store, renderFn, rootElement)
+      await Promise.resolve()
+
+      expect(rootElement.textContent).toBe("") // Empty div because api.render returns ""
+      expect(console.warn).not.toHaveBeenCalled() // No warning for non-existent entity without allowType
+    })
+
+    it("should return a fallback template and warn for a non-existent entity/type with allowType", async () => {
+      const store = setupStore()
+      const renderFn = (api) =>
+        html`<div>${api.render("non-existent-id", { allowType: true })}</div>`
+      mount(store, renderFn, rootElement)
+      await Promise.resolve()
+
+      expect(rootElement.textContent).toBe("Not found: non-existent-id")
+      expect(console.warn).toHaveBeenCalledWith(
+        "No entity or type found: non-existent-id",
+      )
+    })
+
+    it("should return a fallback template and warn for an entity whose type has no render function", async () => {
+      const store = setupStore({
+        "no-render-entity": {
+          id: "no-render-entity",
+          type: "typeWithoutRender",
+        },
+      })
+      const renderFn = (api) =>
+        html`<div>${api.render("no-render-entity")}</div>`
+      mount(store, renderFn, rootElement)
+      await Promise.resolve()
+
+      expect(rootElement.textContent).toBe("No renderer for typeWithoutRender")
+      expect(console.warn).toHaveBeenCalledWith(
+        "No render function for type: typeWithoutRender",
+      )
+    })
+  })
+})

package/types/mount.d.ts

@@ -1,13 +1,38 @@
 import type { TemplateResult } from "lit-html"
 import type { Store, Api as StoreApi } from "@inglorious/store"
 
+/**
+ * The result of a reactive selector.
+ * @template T The type of the selected value.
+ */
+export type ReactiveSelectorResult<T> = {
+  /** The current value of the selected state. */
+  readonly value: T
+  /** A function to stop listening for updates. */
+  unsubscribe: () => void
+}
+
 export type Api = StoreApi & {
   /**
-   * Renders a single entity by its ID.
-   * @param id The ID of the entity to render.
-   * @returns The rendered template or null.
+   * Selects a slice of the application state and returns a reactive object.
+   * The value will update whenever the selected part of the state changes.
+   *
+   * @template T The type of the selected state slice.
+   * @param selectorFn A function that takes the API and returns a slice of the state.
+   * @returns A reactive result object with the current value and an unsubscribe function.
+   */
+  select: <T>(selectorFn: (api: Api) => T) => ReactiveSelectorResult<T>
+
+  /**
+   * Renders an entity or a type component by its ID.
+   * @param id The ID of the entity or type to render.
+   * @param options Rendering options.
+   * @returns The rendered template or an empty string if not found.
    */
-  render: (id: string) => TemplateResult | null
+  render: (
+    id: string,
+    options?: { allowType?: boolean },
+  ) => TemplateResult | string
 }
 
 /**