@inglorious/web 4.0.9 → 4.0.11

package/README.md

@@ -96,8 +96,15 @@ This framework is ideal for both small apps and large business UIs.
 ## When NOT to Use Inglorious Web
 
 - You're frequently mutating thousands of items without virtualization (though our `list` component handles this elegantly)
-- You're building a library that needs to be framework-agnostic
-- Your team is already deeply invested in React/Vue/Angular
+- You need framework-agnostic components for users who might not use Inglorious (use Web Components instead)
+- Your team is already deeply invested in React/Vue/Angular and migration costs outweigh benefits
+
+## When Inglorious Web EXCELS
+
+- Building **internal component libraries** - Types are more customizable than React components
+- Creating **design systems** - Spread, override, and compose behaviors freely
+- Building **pattern libraries** - Ship pre-configured entity types that users can adapt
+- Apps where **predictable state flow** matters more than ecosystem size
 
 ---
 
@@ -145,14 +152,16 @@ This makes it especially suitable for:
 
 ### TL;DR Quick Comparison
 
-| Framework      | Reactivity     | Compiler | Component State | Bundle Size | Learning Curve |
-| -------------- | -------------- | -------- | --------------- | ----------- | -------------- |
-| Inglorious Web | Event-based    | None     | No (store only) | Tiny        | Very Low       |
-| React          | VDOM diffing   | None     | Yes             | Large       | Medium/High    |
-| Vue            | Proxy-based    | Optional | Yes             | Medium      | Medium         |
-| Svelte         | Compiler magic | Required | Yes             | Small       | Medium         |
-| SolidJS        | Fine signals   | None     | No (runs once)  | Tiny        | Medium/High    |
-| Qwik           | Resumable      | Required | Yes             | Small       | Very High      |
+| Framework      | Reactivity     | Build Transform  | Runtime Compiler | Component State | Bundle Size | Learning Curve |
+| -------------- | -------------- | ---------------- | ---------------- | --------------- | ----------- | -------------- |
+| Inglorious Web | Event-based    | None required    | No               | No (store only) | Tiny        | Very Low       |
+| React          | VDOM diffing   | JSX + optional\* | No               | Yes             | Large       | Medium/High    |
+| Vue            | Proxy-based    | SFC (optional)   | Available        | Yes             | Medium      | Medium         |
+| Svelte         | Compiler magic | Required         | No               | Yes             | Small       | Medium         |
+| SolidJS        | Fine signals   | JSX only         | No               | No (runs once)  | Tiny        | Medium/High    |
+| Qwik           | Resumable      | Required         | No               | Yes             | Small       | Very High      |
+
+\*React Compiler (stable 2024+) provides automatic memoization
 
 <details>
 <summary><strong>Click to expand detailed framework comparisons</strong></summary>
@@ -1299,6 +1308,86 @@ See `src/list.js` in the package for the implementation details and the `example
 
 ---
 
+## Building Component Libraries with Inglorious Web
+
+**Inglorious types are uniquely suited for component libraries** because they're fully customizable through JavaScript's spread operator.
+
+### The Pattern
+
+**Library publishes types:**
+
+```javascript
+// @acme/design-system/table.js
+export const table = {
+  render(entity, api) {
+    const type = api.getType(entity.type)
+
+    return html`
+      <table>
+        ${entity.data.map((row) => type.renderRow(entity, row, api))}
+      </table>
+    `
+  },
+
+  renderRow(entity, row, api) {
+    return html`<tr>
+      ${row.name}
+    </tr>`
+  },
+
+  rowClick(entity, row) {
+    entity.selectedRow = row
+  },
+}
+```
+
+**Users customize freely:**
+
+```javascript
+import { table } from "@acme/design-system/table"
+
+// Use as-is
+const simpleTable = { ...table }
+
+// Override methods
+const customTable = {
+  ...table,
+  renderRow(entity, row, api) {
+    return html`<tr class="custom">
+      ${row.name} - ${row.email}
+    </tr>`
+  },
+}
+
+// Compose with behaviors
+import { sortable, exportable } from "@acme/design-system/behaviors"
+
+const advancedTable = [
+  table,
+  sortable,
+  exportable,
+  {
+    rowClick(entity, row) {
+      console.log("Custom click handler", row)
+    },
+  },
+]
+```
+
+### Why This Is Better Than React Components
+
+| Feature                    | React Components               | Inglorious Types                          |
+| -------------------------- | ------------------------------ | ----------------------------------------- |
+| Customize rendering        | Only if `render` prop exposed  | Override `render()` method directly       |
+| Customize behavior         | Only if callback props exposed | Override any method                       |
+| Compose multiple libraries | Wrapper hell / HOCs            | Array composition `[type1, type2, {...}]` |
+| Access internals           | Private - must fork            | Public - spread and override              |
+| Type safety                | Props interface                | Entity schema + method signatures         |
+
+**Users get complete control** without forking your library. They can override rendering, behavior, or both—down to individual methods.
+
+---
+
 ## Using Third-Party Web Components
 
 Inglorious Web works seamlessly with any Web Component library, such as Shoelace, Material Web Components, or Lion. Thanks to lit-html's efficient diffing algorithm, Web Components maintain their internal state even when the full tree re-renders - the component only updates when its properties change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "4.0.9",
+  "version": "4.0.11",
   "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",
@@ -68,8 +68,8 @@
   "dependencies": {
     "@lit-labs/ssr-client": "^1.1.8",
     "lit-html": "^3.3.1",
-    "@inglorious/utils": "3.7.2",
-    "@inglorious/store": "9.0.1"
+    "@inglorious/store": "9.0.1",
+    "@inglorious/utils": "3.7.2"
   },
   "devDependencies": {
     "prettier": "^3.6.2",

package/src/list/index.js

@@ -1,168 +1,7 @@
-import { html } from "lit-html"
-import { ref } from "lit-html/directives/ref.js"
-import { repeat } from "lit-html/directives/repeat.js"
-import { styleMap } from "lit-html/directives/style-map.js"
-
-const LIST_START = 0
-const PRETTY_INDEX = 1
-
-/**
- * @typedef {import('../../types/list').ListEntity} ListEntity
- * @typedef {import('../../types/mount').Api} Api
- * @typedef {import('lit-html').TemplateResult} TemplateResult
- */
+import { logic } from "./logic.js"
+import { rendering } from "./rendering.js"
 
 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 } =
-      entity
-    const height = itemHeight || estimatedHeight
-
-    const start = Math.max(
-      LIST_START,
-      Math.floor(scrollTop / height) - bufferSize,
-    )
-    const visibleCount = Math.ceil(viewportHeight / height)
-    const end = Math.min(start + visibleCount + bufferSize, items.length)
-
-    if (
-      entity.visibleRange.start === start &&
-      entity.visibleRange.end === end
-    ) {
-      return
-    }
-
-    entity.scrollTop = scrollTop
-    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
-
-    entity.itemHeight = firstItem.offsetHeight
-    entity.visibleRange = {
-      start: 0,
-      end: Math.ceil(entity.viewportHeight / entity.itemHeight),
-    }
-  },
-
-  /**
-   * Renders the virtualized list component.
-   * @param {ListEntity} entity
-   * @param {Api} api
-   * @returns {TemplateResult}
-   */
-  render(entity, api) {
-    const { items, visibleRange, viewportHeight, itemHeight, estimatedHeight } =
-      entity
-    const type = api.getType(entity.type)
-
-    if (!items) {
-      console.warn(`list entity ${entity.id} needs 'items'`)
-      return html``
-    }
-
-    if (!type.renderItem) {
-      console.warn(`type ${entity.type} needs 'renderItem' method`)
-      return html``
-    }
-
-    const visibleItems = items.slice(visibleRange.start, visibleRange.end)
-    const height = itemHeight || estimatedHeight
-    const totalHeight = items.length * height
-
-    return html`
-      <div
-        style=${styleMap({ height: `${viewportHeight}px`, overflow: "auto" })}
-        @scroll=${(e) => api.notify(`#${entity.id}:scroll`, e.target)}
-        ${ref((el) => {
-          if (el && !itemHeight) {
-            queueMicrotask(() => {
-              api.notify(`#${entity.id}:mount`, el)
-            })
-          }
-        })}
-      >
-        <div
-          style=${styleMap({
-            height: `${totalHeight}px`,
-            position: "relative",
-          })}
-        >
-          ${repeat(
-            visibleItems,
-            (item) => item.id,
-            (item, index) => {
-              const absoluteIndex = visibleRange.start + index
-              const top = absoluteIndex * height
-
-              return html`
-                <div
-                  style=${styleMap({
-                    position: "absolute",
-                    top: `${top}px`,
-                    width: "100%",
-                  })}
-                  data-index=${absoluteIndex}
-                >
-                  ${type.renderItem(
-                    entity,
-                    { item, index: absoluteIndex },
-                    api,
-                  )}
-                </div>
-              `
-            },
-          )}
-        </div>
-      </div>
-    `
-  },
-
-  /**
-   * Default item renderer.
-   * @param {any} item
-   * @param {number} index
-   * @param {Api} api
-   * @returns {TemplateResult}
-   */
-  // eslint-disable-next-line no-unused-vars
-  renderItem(entity, { item, index }, api) {
-    return html`<div class="iw-list-item">
-      ${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 }
-  entity.viewportHeight ??= 600
-  entity.bufferSize ??= 5
-  entity.itemHeight ??= null
-  entity.estimatedHeight ??= 50
+  ...logic,
+  ...rendering,
 }

package/src/list/logic.js

@@ -0,0 +1,75 @@
+/**
+ * @typedef {import('../../types/list').ListEntity} ListEntity
+ * @typedef {import('../../types/mount').Api} Api
+ * @typedef {import('lit-html').TemplateResult} TemplateResult
+ */
+
+const LIST_START = 0
+
+export const logic = {
+  /**
+   * 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 } =
+      entity
+    const height = itemHeight || estimatedHeight
+
+    const start = Math.max(
+      LIST_START,
+      Math.floor(scrollTop / height) - bufferSize,
+    )
+    const visibleCount = Math.ceil(viewportHeight / height)
+    const end = Math.min(start + visibleCount + bufferSize, items.length)
+
+    if (
+      entity.visibleRange.start === start &&
+      entity.visibleRange.end === end
+    ) {
+      return
+    }
+
+    entity.scrollTop = scrollTop
+    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
+
+    entity.itemHeight = firstItem.offsetHeight
+    entity.visibleRange = {
+      start: 0,
+      end: Math.ceil(entity.viewportHeight / entity.itemHeight),
+    }
+  },
+}
+
+/**
+ * Resets the list entity state.
+ * @param {ListEntity} entity
+ */
+function resetList(entity) {
+  entity.scrollTop = 0
+  entity.visibleRange ??= { start: 0, end: 20 }
+  entity.viewportHeight ??= 600
+  entity.bufferSize ??= 5
+  entity.itemHeight ??= null
+  entity.estimatedHeight ??= 50
+}

package/src/list/rendering.js

@@ -0,0 +1,105 @@
+/**
+ * @typedef {import('../../types/mount').Api} Api
+ * @typedef {import('../../types/list').ListEntity} ListEntity
+ * @typedef {import('lit-html').TemplateResult} TemplateResult
+ */
+
+import { html } from "lit-html"
+import { ref } from "lit-html/directives/ref.js"
+import { repeat } from "lit-html/directives/repeat.js"
+import { styleMap } from "lit-html/directives/style-map.js"
+
+const PRETTY_INDEX = 1
+/**
+ * Rendering logic for the virtualized list component.
+ */
+export const rendering = {
+  /**
+   * Renders the virtualized list component.
+   * @param {ListEntity} entity The list entity state.
+   * @param {Api} api The API object.
+   * @returns {TemplateResult} The rendered list.
+   */
+  render(entity, api) {
+    const { items, visibleRange, viewportHeight, itemHeight, estimatedHeight } =
+      entity
+    const type = api.getType(entity.type)
+
+    if (!items) {
+      console.warn(`list entity ${entity.id} needs 'items'`)
+      return html``
+    }
+
+    if (!type.renderItem) {
+      console.warn(`type ${entity.type} needs 'renderItem' method`)
+      return html``
+    }
+
+    const visibleItems = items.slice(visibleRange.start, visibleRange.end)
+    const height = itemHeight || estimatedHeight
+    const totalHeight = items.length * height
+
+    return html`
+      <div
+        style=${styleMap({ height: `${viewportHeight}px`, overflow: "auto" })}
+        @scroll=${(e) => api.notify(`#${entity.id}:scroll`, e.target)}
+        ${ref((el) => {
+          if (el && !itemHeight) {
+            queueMicrotask(() => {
+              api.notify(`#${entity.id}:mount`, el)
+            })
+          }
+        })}
+      >
+        <div
+          style=${styleMap({
+            height: `${totalHeight}px`,
+            position: "relative",
+          })}
+        >
+          ${repeat(
+            visibleItems,
+            (item) => item.id,
+            (item, index) => {
+              const absoluteIndex = visibleRange.start + index
+              const top = absoluteIndex * height
+
+              return html`
+                <div
+                  style=${styleMap({
+                    position: "absolute",
+                    top: `${top}px`,
+                    width: "100%",
+                  })}
+                  data-index=${absoluteIndex}
+                >
+                  ${type.renderItem(
+                    entity,
+                    { item, index: absoluteIndex },
+                    api,
+                  )}
+                </div>
+              `
+            },
+          )}
+        </div>
+      </div>
+    `
+  },
+
+  /**
+   * Default item renderer.
+   * @param {ListEntity} entity The list entity.
+   * @param {object} payload The payload for rendering the item.
+   * @param {any} payload.item The item data.
+   * @param {number} payload.index The item's absolute index in the full list.
+   * @param {Api} api The API object.
+   * @returns {TemplateResult} The rendered list item.
+   */
+  // eslint-disable-next-line no-unused-vars
+  renderItem(entity, { item, index }, api) {
+    return html`<div class="iw-list-item">
+      ${index + PRETTY_INDEX}. ${JSON.stringify(item)}
+    </div>`
+  },
+}

package/src/table/rendering.js

@@ -1,3 +1,11 @@
+/**
+ * @typedef {import('../../types/api').API} API
+ * @typedef {import('../../types/table').TableColumn} TableColumn
+ * @typedef {import('../../types/table').TableEntity} TableEntity
+ * @typedef {import('../../types/table').TableRow} TableRow
+ * @typedef {import('lit-html').TemplateResult} TemplateResult
+ */
+
 import { html } from "lit-html"
 import { classMap } from "lit-html/directives/class-map.js"
 import { ref } from "lit-html/directives/ref.js"
@@ -12,14 +20,28 @@ const LAST_PAGE = 1
 const PRETTY_PAGE = 1
 const PERCENTAGE_TO_FLEX = 0.01
 
+/**
+ * Rendering logic for the table component.
+ */
 export const rendering = {
+  /**
+   * Measures and sets initial column widths.
+   * This is called after the initial render to capture the "auto" widths of columns.
+   * @param {TableEntity} entity The table entity.
+   * @param {HTMLElement} containerEl The header row element containing the columns.
+   */
   mount(entity, containerEl) {
     const columns = containerEl.querySelectorAll(":scope > *")
     ;[...columns].forEach((column, index) => {
       entity.columns[index].width = column.offsetWidth
     })
   },
-
+  /**
+   * Renders the main table component.
+   * @param {TableEntity} entity The table entity.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered table.
+   */
   render(entity, api) {
     const type = api.getType(entity.type)
 
@@ -28,7 +50,12 @@ export const rendering = {
       ${type.renderFooter(entity, api)}
     </div> `
   },
-
+  /**
+   * Renders the table header.
+   * @param {TableEntity} entity The table entity.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered header.
+   */
   renderHeader(entity, api) {
     const type = api.getType(entity.type)
 
@@ -57,7 +84,14 @@ export const rendering = {
       ${entity.search && type.renderSearchbar(entity, api)}
     </div>`
   },
-
+  /**
+   * Renders a single column in the header.
+   * @param {TableEntity} entity The table entity.
+   * @param {object} payload The payload.
+   * @param {TableColumn} payload.column The column definition.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered header column.
+   */
   renderHeaderColumn(entity, { column }, api) {
     return html`<div
       class="iw-table-header-column"
@@ -75,7 +109,12 @@ export const rendering = {
       ${column.isFilterable && filters.render(entity, column, api)}
     </div>`
   },
-
+  /**
+   * Renders the search bar.
+   * @param {TableEntity} entity The table entity.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered search bar.
+   */
   renderSearchbar(entity, api) {
     return html`<input
       name="search"
@@ -87,7 +126,12 @@ export const rendering = {
       class="iw-table-searchbar"
     />`
   },
-
+  /**
+   * Renders the table body with rows.
+   * @param {TableEntity} entity The table entity.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered table body.
+   */
   renderBody(entity, api) {
     const type = api.getType(entity.type)
 
@@ -99,7 +143,15 @@ export const rendering = {
       )}
     </div>`
   },
-
+  /**
+   * Renders a single row in the table body.
+   * @param {TableEntity} entity The table entity.
+   * @param {object} payload The payload.
+   * @param {TableRow} payload.row The row data.
+   * @param {number} payload.index The row index.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered row.
+   */
   renderRow(entity, { row, index }, api) {
     const type = api.getType(entity.type)
     const rowId = row[entity.rowId ?? "id"]
@@ -119,7 +171,15 @@ export const rendering = {
       )}
     </div>`
   },
-
+  /**
+   * Renders a single cell within a row.
+   * @param {TableEntity} entity The table entity.
+   * @param {object} payload The payload.
+   * @param {any} payload.cell The cell data.
+   * @param {number} payload.index The column index.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered cell.
+   */
   renderCell(entity, { cell, index }, api) {
     const type = api.getType(entity.type)
     const column = entity.columns[index]
@@ -136,10 +196,22 @@ export const rendering = {
     </div>`
   },
 
-  renderValue(_, { value }) {
+  /**
+   * Renders the value within a cell. This can be overridden for custom formatting.
+   * @param {TableEntity} _entity The table entity (ignored).
+   * @param {object} payload The payload.
+   * @param {any} payload.value The value to render.
+   * @returns {any} The value to be rendered.
+   */
+  renderValue(_entity, { value }) {
     return value
   },
-
+  /**
+   * Renders the table footer.
+   * @param {TableEntity} entity The table entity.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered footer.
+   */
   renderFooter(entity, api) {
     const type = api.getType(entity.type)
     const pagination = getPaginationInfo(entity)
@@ -172,7 +244,13 @@ export const rendering = {
       </div>
     </div>`
   },
-
+  /**
+   * Renders the pagination controls.
+   * @param {TableEntity} entity The table entity.
+   * @param {object} pagination The pagination info object from `getPaginationInfo`.
+   * @param {API} api The API object.
+   * @returns {TemplateResult} The rendered pagination controls.
+   */
   renderPagination(entity, pagination, api) {
     return html`<div class="iw-table-row">
       <button
@@ -226,6 +304,11 @@ export const rendering = {
   },
 }
 
+/**
+ * Generates the style string for a column.
+ * @param {TableColumn} column The column definition.
+ * @returns {string} The style string.
+ */
 function getColumnStyle(column) {
   if (typeof column.width === "string") {
     if (column.width?.endsWith("%")) {
@@ -240,6 +323,11 @@ function getColumnStyle(column) {
   return `width: ${column.width}px`
 }
 
+/**
+ * Gets the appropriate sort icon for a given direction.
+ * @param {"asc"|"desc"|null} direction The sort direction.
+ * @returns {string} The sort icon.
+ */
 function getSortIcon(direction) {
   switch (direction) {
     case "asc":

package/types/list.d.ts

@@ -2,58 +2,66 @@ import type { TemplateResult } from "lit-html"
 import type { Api } from "./mount"
 
 /**
- * Represents the visible range of items in the list.
+ * Represents a single item in the list's data array.
+ * It's a generic record but should ideally have a unique `id`.
  */
-export interface VisibleRange {
-  start: number
-  end: number
-}
+export type ListItem = Record<string, any> & { id: string | number }
 
 /**
- * Represents the state of a list entity.
+ * Represents the state of a virtualized list entity.
  */
-export interface ListEntity<T = any> {
+export interface ListEntity<T extends ListItem = ListItem> {
   /** A unique identifier for the list entity. */
   id: string | number
-  /** The entity type (usually 'list'). */
+
+  /** The entity type, used to look up rendering logic. */
   type: string
-  /** The array of items to render. */
+
+  /** The full array of items for the list. */
   items: T[]
-  /** The current scroll position of the list container. */
+
+  /** The current scroll position from the top in pixels. */
   scrollTop: number
-  /** The range of items currently visible (plus buffer). */
-  visibleRange: VisibleRange
-  /** The height of the viewport in pixels. */
+
+  /** The start and end indices of the currently visible items (including buffer). */
+  visibleRange: { start: number; end: number }
+
+  /** The height of the visible viewport in pixels. */
   viewportHeight: number
-  /** The number of extra items to render above and below the visible range. */
+
+  /** The number of items to render outside the viewport (above and below). */
   bufferSize: number
-  /** The fixed height of each item in pixels, or null if measuring. */
+
+  /** The measured height of a single item in pixels. Null until measured on mount. */
   itemHeight: number | null
-  /** The estimated height of an item, used before measurement. */
+
+  /** An estimated height for items used for calculations before they are measured. */
   estimatedHeight: number
+
   /** Any other custom properties. */
   [key: string]: any
 }
 
 /**
- * The list type implementation.
+ * The list type implementation, combining logic and rendering.
  */
 export declare const list: {
   /**
    * Initializes the list entity with default state.
-   * @param entity The list entity.
+   * @param entity The list entity to initialize.
    */
   create(entity: ListEntity): void
 
   /**
-   * Handles the scroll event to update the visible range.
+   * Handles the scroll event to update the visible range of items.
    * @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.
+   * Mounts the list, measuring the first item to determine the `itemHeight`
+   * for accurate virtualization calculations.
    * @param entity The list entity.
    * @param containerEl The scrolling container element.
    */
@@ -67,10 +75,17 @@ export declare const list: {
   render(entity: ListEntity, api: Api): TemplateResult
 
   /**
-   * Default item renderer.
-   * @param item The item to render.
-   * @param index The index of the item.
+   * Renders a single item in the list. This is a default implementation
+   * and is expected to be overridden by a specific list type.
+   * @param entity The list entity.
+   * @param payload The payload for rendering the item.
+   * @param payload.item The item data.
+   * @param payload.index The item's absolute index in the full list.
    * @param api The store API.
    */
-  renderItem(item: any, index: number, api: Api): TemplateResult
+  renderItem(
+    entity: ListEntity,
+    payload: { item: ListItem; index: number },
+    api: Api,
+  ): TemplateResult
 }

package/types/table.d.ts

@@ -1,5 +1,11 @@
 import type { TemplateResult } from "lit-html"
 import type { Api } from "./mount"
+import type { SelectOption } from "./select"
+
+/**
+ * Represents a single row of data in the table.
+ */
+export type TableRow = Record<string, any>
 
 /**
  * Represents a column definition for the table.
@@ -18,17 +24,17 @@ export interface TableColumn {
   /** Filter configuration. */
   filter?: {
     type: "text" | "number" | "range" | "select" | "date" | "time" | "datetime"
-    options?: any[]
+    options?: SelectOption[]
     [key: string]: any
   }
-  /** The width of the column. */
-  width?: number
+  /** The width of the column, in pixels or as a string (e.g., '10%'). */
+  width?: number | string
   /** Optional formatter key or function. */
   formatter?: string | ((value: any) => any)
-  /** Custom sort function. */
-  sortFn?: (a: any, b: any) => number
-  /** Custom filter function. */
-  filterFn?: (row: any, filterValue: any) => boolean
+  /** Custom sort function for a column, operating on two rows. */
+  sortFn?: (a: TableRow, b: TableRow) => number
+  /** Custom filter function for a column, operating on a single row. */
+  filterFn?: (row: TableRow, filterValue: any) => boolean
   /** Custom format function. */
   format?: (value: any) => string
   /** Any other custom properties. */
@@ -38,7 +44,7 @@ export interface TableColumn {
 /**
  * Represents the state of a table entity.
  */
-export interface TableEntity<T = any> {
+export interface TableEntity<T extends TableRow = TableRow> {
   /** A unique identifier for the table entity. */
   id: string | number
   /** The entity type. */
@@ -52,11 +58,13 @@ export interface TableEntity<T = any> {
   /** Filtering state. */
   filters: Record<string, any>
   /** Search state. */
-  search: { value: string } | null
+  search: { value: string; placeholder?: string } | null
   /** Selected row IDs. */
   selection: (string | number)[]
   /** Pagination state. */
   pagination: { page: number; pageSize: number } | null
+  /** The property on a row object that uniquely identifies it. Defaults to 'id'. */
+  rowId?: string
   /** Whether multi-select is enabled. */
   isMultiSelect: boolean
   /** Any other custom properties. */
@@ -198,35 +206,43 @@ export declare const table: {
   /**
    * Renders a single row.
    * @param entity The table entity.
-   * @param item The data item for the row.
-   * @param index The index of the row.
+   * @param payload The payload for rendering the row.
+   * @param payload.row The data item for the row.
+   * @param payload.index The index of the row.
    * @param api The store API.
    */
   renderRow(
     entity: TableEntity,
-    item: any,
-    index: number,
+    payload: { row: TableRow; index: number },
     api: Api,
   ): TemplateResult
 
   /**
    * Renders a single cell.
    * @param entity The table entity.
-   * @param item The data item for the row.
-   * @param column The column definition.
+   * @param payload The payload for rendering the cell.
+   * @param payload.cell The data for the cell.
+   * @param payload.index The column index of the cell.
    * @param api The store API.
    */
   renderCell(
     entity: TableEntity,
-    item: any,
-    column: TableColumn,
+    payload: { cell: any; index: number },
     api: Api,
   ): TemplateResult
 
   /**
    * Renders the value of a cell.
-   * @param value The raw value from the data item.
-   * @param column The column definition.
+   * @param entity The table entity.
+   * @param payload The payload for rendering the value.
+   * @param payload.value The raw value from the data item.
+   * @param payload.column The column definition.
+   * @param payload.index The column index.
+   * @param api The store API.
    */
-  renderValue(value: any, column: TableColumn): any
+  renderValue(
+    entity: TableEntity,
+    payload: { value: any; column: TableColumn; index: number },
+    api: Api,
+  ): any
 }