@inglorious/web 2.5.0 → 2.6.1

package/src/table/logic.js

@@ -1,14 +1,24 @@
 /* eslint-disable no-magic-numbers */
 
-export const logic = {
-  init(entity) {
-    initTable(entity)
-  },
+/**
+ * @typedef {import('../../types/table').TableEntity} TableEntity
+ * @typedef {import('../../types/table').TableColumn} TableColumn
+ */
 
+export const logic = {
+  /**
+   * Resets the table entity with default state.
+   * @param {TableEntity} entity
+   */
   create(entity) {
     initTable(entity)
   },
 
+  /**
+   * Toggles sorting for a column.
+   * @param {TableEntity} entity
+   * @param {string} columnId
+   */
   sortChange(entity, columnId) {
     const column = entity.columns.find((c) => c.id === columnId)
     if (!column?.isSortable) return
@@ -34,10 +44,19 @@ export const logic = {
     }
   },
 
+  /**
+   * Clears all sorts.
+   * @param {TableEntity} entity
+   */
   sortsClear(entity) {
     entity.sorts = []
   },
 
+  /**
+   * Updates a filter value for a column.
+   * @param {TableEntity} entity
+   * @param {{ columnId: string, value: any }} payload
+   */
   filterChange(entity, { columnId, value }) {
     if (value == null || value === "") {
       delete entity.filters[columnId]
@@ -51,6 +70,10 @@ export const logic = {
     }
   },
 
+  /**
+   * Clears all filters.
+   * @param {TableEntity} entity
+   */
   filtersClear(entity) {
     entity.filters = {}
     if (entity.pagination) {
@@ -58,10 +81,20 @@ export const logic = {
     }
   },
 
+  /**
+   * Updates the search term.
+   * @param {TableEntity} entity
+   * @param {string} search
+   */
   searchChange(entity, search) {
     entity.search.value = search
   },
 
+  /**
+   * Changes the current page.
+   * @param {TableEntity} entity
+   * @param {number} page
+   */
   pageChange(entity, page) {
     if (!entity.pagination) return
 
@@ -71,6 +104,10 @@ export const logic = {
     entity.pagination.page = Math.max(0, Math.min(page, totalPages - 1))
   },
 
+  /**
+   * Moves to the next page.
+   * @param {TableEntity} entity
+   */
   pageNext(entity) {
     if (!entity.pagination) return
     const totalPages = Math.ceil(
@@ -82,11 +119,20 @@ export const logic = {
     )
   },
 
+  /**
+   * Moves to the previous page.
+   * @param {TableEntity} entity
+   */
   pagePrev(entity) {
     if (!entity.pagination) return
     entity.pagination.page = Math.max(entity.pagination.page - 1, 0)
   },
 
+  /**
+   * Changes the page size.
+   * @param {TableEntity} entity
+   * @param {number} pageSize
+   */
   pageSizeChange(entity, pageSize) {
     if (!entity.pagination) return
 
@@ -94,6 +140,11 @@ export const logic = {
     entity.pagination.page = 0
   },
 
+  /**
+   * Selects a row.
+   * @param {TableEntity} entity
+   * @param {string|number} rowId
+   */
   rowSelect(entity, rowId) {
     if (!entity.isMultiSelect) {
       entity.selection = []
@@ -104,6 +155,11 @@ export const logic = {
     }
   },
 
+  /**
+   * Deselects a row.
+   * @param {TableEntity} entity
+   * @param {string|number} rowId
+   */
   rowDeselect(entity, rowId) {
     const index = entity.selection.indexOf(rowId)
     if (index !== -1) {
@@ -111,6 +167,11 @@ export const logic = {
     }
   },
 
+  /**
+   * Toggles row selection.
+   * @param {TableEntity} entity
+   * @param {string|number} rowId
+   */
   rowToggle(entity, rowId) {
     const index = entity.selection.indexOf(rowId)
 
@@ -125,6 +186,10 @@ export const logic = {
     }
   },
 
+  /**
+   * Toggles selection of all currently visible rows.
+   * @param {TableEntity} entity
+   */
   rowsToggleAll(entity) {
     const rows = getRows(entity)
     const allSelected = rows.every((row) => entity.selection.includes(row.id))
@@ -145,6 +210,10 @@ export const logic = {
     }
   },
 
+  /**
+   * Selects all currently visible rows.
+   * @param {TableEntity} entity
+   */
   rowsSelectAll(entity) {
     const rows = getRows(entity)
     rows.forEach((row) => {
@@ -154,13 +223,22 @@ export const logic = {
     })
   },
 
+  /**
+   * Clears all row selections.
+   * @param {TableEntity} entity
+   */
   selectionClear(entity) {
     entity.selection.length = 0
   },
 }
 
-// Helper functions outside the type (like form helpers)
+// Helper functions
 
+/**
+ * Gets the processed rows (filtered, searched, sorted, paginated).
+ * @param {TableEntity} entity
+ * @returns {any[]}
+ */
 export function getRows(entity) {
   let rows = entity.data
   rows = applyFilters(entity, rows)
@@ -171,6 +249,11 @@ export function getRows(entity) {
   return rows
 }
 
+/**
+ * Gets the total number of rows after filtering and searching.
+ * @param {TableEntity} entity
+ * @returns {number}
+ */
 export function getTotalRows(entity) {
   let rows = entity.data
   rows = applyFilters(entity, rows)
@@ -178,6 +261,11 @@ export function getTotalRows(entity) {
   return rows.length
 }
 
+/**
+ * Gets pagination information.
+ * @param {TableEntity} entity
+ * @returns {object|null}
+ */
 export function getPaginationInfo(entity) {
   if (!entity.pagination) return null
 
@@ -199,28 +287,62 @@ export function getPaginationInfo(entity) {
   }
 }
 
+/**
+ * Gets the sort direction for a column.
+ * @param {TableEntity} entity
+ * @param {string} columnId
+ * @returns {"asc"|"desc"|null}
+ */
 export function getSortDirection(entity, columnId) {
   const sort = entity.sorts.find((s) => s.column === columnId)
   return sort?.direction || null
 }
 
+/**
+ * Gets the sort index (priority) for a column.
+ * @param {TableEntity} entity
+ * @param {string} columnId
+ * @returns {number}
+ */
 export function getSortIndex(entity, columnId) {
   return entity.sorts.findIndex((s) => s.column === columnId)
 }
 
+/**
+ * Gets the filter value for a column.
+ * @param {TableEntity} entity
+ * @param {string} columnId
+ * @returns {any}
+ */
 export function getFilter(entity, columnId) {
   return entity.filters[columnId]
 }
 
+/**
+ * Checks if a row is selected.
+ * @param {TableEntity} entity
+ * @param {string|number} rowId
+ * @returns {boolean}
+ */
 export function isRowSelected(entity, rowId) {
   return entity.selection.includes(rowId)
 }
 
+/**
+ * Checks if all visible rows are selected.
+ * @param {TableEntity} entity
+ * @returns {boolean}
+ */
 export function isAllSelected(entity) {
   const rows = getRows(entity)
   return rows.length && rows.every((row) => entity.selection.includes(row.id))
 }
 
+/**
+ * Checks if some (but not all) visible rows are selected.
+ * @param {TableEntity} entity
+ * @returns {boolean}
+ */
 export function isSomeSelected(entity) {
   const rows = getRows(entity)
   const selectedCount = rows.filter((row) =>
@@ -229,6 +351,12 @@ export function isSomeSelected(entity) {
   return selectedCount && selectedCount < rows.length
 }
 
+// Private helper functions
+
+/**
+ * Initializes the table state.
+ * @param {TableEntity} entity
+ */
 function initTable(entity) {
   entity.data ??= []
 
@@ -276,6 +404,11 @@ function initTable(entity) {
   }
 }
 
+/**
+ * Infers the column type from a value.
+ * @param {any} value
+ * @returns {string}
+ */
 function getDefaultColumnType(value) {
   if (typeof value === "number") return "number"
   if (typeof value === "boolean") return "boolean"
@@ -283,6 +416,11 @@ function getDefaultColumnType(value) {
   return "string"
 }
 
+/**
+ * Gets the default filter configuration for a column type.
+ * @param {string} type
+ * @returns {object}
+ */
 function getDefaultColumnFilter(type) {
   if (type === "number") return { type: "range" }
   if (type === "boolean")
@@ -291,6 +429,11 @@ function getDefaultColumnFilter(type) {
   return { type: "text" }
 }
 
+/**
+ * Gets the default column width based on filter type.
+ * @param {string} filterType
+ * @returns {number}
+ */
 function getDefaultColumnWidth(filterType) {
   if (filterType === "number") return 70
   if (filterType === "range") return 100
@@ -301,6 +444,12 @@ function getDefaultColumnWidth(filterType) {
   return 200
 }
 
+/**
+ * Applies filters to the data.
+ * @param {TableEntity} entity
+ * @param {any[]} rows
+ * @returns {any[]}
+ */
 function applyFilters(entity, rows) {
   if (!Object.keys(entity.filters).length) {
     return rows
@@ -338,6 +487,12 @@ function applyFilters(entity, rows) {
   })
 }
 
+/**
+ * Applies search to the data.
+ * @param {TableEntity} entity
+ * @param {any[]} rows
+ * @returns {any[]}
+ */
 function applySearch(entity, rows) {
   if (!entity.search?.value) {
     return rows
@@ -354,6 +509,12 @@ function applySearch(entity, rows) {
   )
 }
 
+/**
+ * Applies sorting to the data.
+ * @param {TableEntity} entity
+ * @param {any[]} rows
+ * @returns {any[]}
+ */
 function applySorts(entity, rows) {
   if (!entity.sorts.length) {
     return rows
@@ -385,6 +546,12 @@ function applySorts(entity, rows) {
   })
 }
 
+/**
+ * Applies pagination to the data.
+ * @param {TableEntity} entity
+ * @param {any[]} rows
+ * @returns {any[]}
+ */
 function applyPagination(entity, rows) {
   if (!entity.pagination) {
     return rows
@@ -395,6 +562,11 @@ function applyPagination(entity, rows) {
   return rows.slice(start, start + pageSize)
 }
 
+/**
+ * Capitalizes the first letter of a string.
+ * @param {string} str
+ * @returns {string}
+ */
 function capitalize(str) {
   const [firstChar, ...rest] = str
   return [firstChar.toUpperCase(), ...rest].join("")

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,2 +1,6 @@
+export * from "./form"
+export * from "./list"
 export * from "./mount"
 export * from "./router"
+export * from "./select"
+export * from "./table"

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

@@ -0,0 +1,136 @@
+import type { TemplateResult } from "lit-html"
+import type { Api } from "./mount"
+
+/**
+ * Represents an option in the select component.
+ * Can be a simple string/number or an object with value and label.
+ */
+export type SelectOption =
+  | string
+  | number
+  | {
+      value: string | number
+      label?: string
+      disabled?: boolean
+      [key: string]: any
+    }
+
+/**
+ * Represents the state of a select entity.
+ */
+export interface SelectEntity {
+  /** A unique identifier for the select entity. */
+  id: string | number
+  /** The entity type (usually 'select'). */
+  type: string
+  /** The list of options available for selection. */
+  options: SelectOption[]
+  /** Whether the dropdown is currently open. */
+  isOpen: boolean
+  /** The current search term entered by the user. */
+  searchTerm: string
+  /** The index of the currently focused option (for keyboard navigation). */
+  focusedIndex: number
+  /** Whether multiple options can be selected. */
+  isMulti: boolean
+  /** The currently selected value(s). */
+  selectedValue: string | number | (string | number)[] | null
+  /** Whether the options are currently loading. */
+  isLoading: boolean
+  /** Whether the select component is disabled. */
+  isDisabled: boolean
+  /** Whether the user can search through options. */
+  isSearchable: boolean
+  /** Whether the selection can be cleared. */
+  isClearable: boolean
+  /** Whether new options can be created by the user. */
+  isCreatable: boolean
+  /** Placeholder text to display when no value is selected. */
+  placeholder: string
+  /** Message to display when no options match the search term. */
+  noOptionsMessage: string
+  /** Message to display while options are loading. */
+  loadingMessage: string
+  /** Property name to group options by. */
+  groupBy: string | null
+}
+
+/**
+ * The select type implementation.
+ */
+export declare const select: {
+  /**
+   * Initializes the select entity with default state.
+   * @param {SelectEntity} entity
+   */
+  create(entity: SelectEntity): void
+
+  /**
+   * Renders the select component.
+   * @param entity The select entity.
+   * @param api The store API.
+   */
+  render(entity: SelectEntity, api: Api): TemplateResult
+
+  /**
+   * Opens the select dropdown.
+   * @param entity The select entity.
+   */
+  open(entity: SelectEntity): void
+
+  /**
+   * Closes the select dropdown.
+   * @param entity The select entity.
+   */
+  close(entity: SelectEntity): void
+
+  /**
+   * Toggles the select dropdown open/closed state.
+   * @param entity The select entity.
+   */
+  toggle(entity: SelectEntity): void
+
+  /**
+   * Selects an option.
+   * @param entity The select entity.
+   * @param option The option to select.
+   */
+  optionSelect(entity: SelectEntity, option: SelectOption): void
+
+  /**
+   * Clears the current selection.
+   * @param entity The select entity.
+   */
+  clear(entity: SelectEntity): void
+
+  /**
+   * Updates the search term and filters options.
+   * @param entity The select entity.
+   * @param term The new search term.
+   */
+  searchChange(entity: SelectEntity, term: string): void
+
+  /**
+   * Moves focus to the next option.
+   * @param entity The select entity.
+   */
+  focusNext(entity: SelectEntity): void
+
+  /**
+   * Moves focus to the previous option.
+   * @param entity The select entity.
+   */
+  focusPrev(entity: SelectEntity): void
+
+  /**
+   * Moves focus to the first option.
+   * @param entity The select entity.
+   */
+  focusFirst(entity: SelectEntity): void
+
+  /**
+   * Moves focus to the last option.
+   * @param entity The select entity.
+   */
+  focusLast(entity: SelectEntity): void
+}