@tipolox/litgrid-web 1.1.0 → 1.2.0

package/src/components/DataGrid.ts

@@ -7,6 +7,11 @@ import {
   type GridConfig,
   type GridFilter,
   type GridSelection,
+  type GridRowKey,
+  type SelectionChangeDetail,
+  type GridExternalState,
+  type GridQueryChangeDetail,
+  type SortDirection,
   type SelectionIntent
 } from '@tipolox/litgrid-core'
 import {
@@ -118,6 +123,7 @@ export class DataGrid extends LitElement {
   private previousBodyCursor = ''
   private previousBodyUserSelect = ''
   private activeHeaderMenu: string | null = null
+  private headerMenuCapabilities = { sortable: true, filterable: true }
   private columnChooserOpen = false
   private columnChooserPosition: { left: number; top: number } | null = null
   private quickSearchVisible = false
@@ -145,6 +151,7 @@ export class DataGrid extends LitElement {
   private shouldRestoreHeaderMenuFocus = false
   private screenReaderMessage = ''
   private lastScreenReaderAnnouncement = ''
+  private paginationFocusTarget: HTMLButtonElement | null = null
 
   // Use a larger cap (2^26) to avoid hitting browser element-height limits.
 
@@ -171,6 +178,21 @@ export class DataGrid extends LitElement {
     this.ariaLabel = 'Data grid'
     this.ariaDescription = ''
     this.screenReaderAnnouncements = true
+    this.engine.onSelectionChange(detail => {
+      this.requestUpdate()
+      this.dispatchEvent(new CustomEvent<SelectionChangeDetail>('selection-change', {
+        detail, bubbles: true, composed: true
+      }))
+    })
+    this.engine.onQueryChange(detail => {
+      this.quickSearchDraft = detail.query.search
+      this.clearBestFitWidths()
+      this.resetVerticalScroll()
+      this.requestUpdate()
+      this.dispatchEvent(new CustomEvent<GridQueryChangeDetail>('query-change', {
+        detail, bubbles: true, composed: true
+      }))
+    })
   }
 
   static styles = [lightThemeStyles, darkThemeStyles, css`
@@ -701,7 +723,17 @@ export class DataGrid extends LitElement {
     this.updateScrollbarWidth()
   }
 
+  willUpdate() {
+    // Reconcile after schema and persisted visibility settle, before triggers disappear.
+    this.reconcileHeaderMenuCapabilities()
+  }
+
       updated() {
+    const paginationTarget = this.paginationFocusTarget
+    this.paginationFocusTarget = null
+    if (paginationTarget?.isConnected && paginationTarget.disabled) {
+      this.renderRoot.querySelector<HTMLElement>('.pagination button:not([disabled]), .pagination select')?.focus()
+    }
     this.updateScrollbarWidth()
 
     if (this.shouldFocusViewport) {
@@ -1162,6 +1194,7 @@ export class DataGrid extends LitElement {
       })
     }
         const isOpening = this.activeHeaderMenu !== columnKey
+    this.headerMenuCapabilities = this.getColumnCapabilities(columnKey)
 
     this.activeHeaderMenu = isOpening ? columnKey : null
     this.headerMenuTrigger = isOpening && event.currentTarget instanceof HTMLButtonElement
@@ -1171,6 +1204,20 @@ export class DataGrid extends LitElement {
     this.requestUpdate()
   }
 
+  private getColumnCapabilities(columnKey: string) {
+    const column = this.getResolvedColumns().find(column => column.key === columnKey)
+    return { sortable: !!column && column.sortable !== false, filterable: !!column && column.filterable !== false }
+  }
+
+  private reconcileHeaderMenuCapabilities() {
+    if (this.activeHeaderMenu === null) return
+    const next = this.getColumnCapabilities(this.activeHeaderMenu)
+    if (!this.isColumnVisible(this.activeHeaderMenu)
+        || next.sortable !== this.headerMenuCapabilities.sortable || next.filterable !== this.headerMenuCapabilities.filterable) {
+      this.closeHeaderMenu(true)
+    }
+  }
+
     private closeHeaderMenu(restoreFocus = false) {
       if (this.activeHeaderMenu === null && !this.columnChooserOpen) return
       this.activeHeaderMenu = null
@@ -1320,6 +1367,10 @@ export class DataGrid extends LitElement {
 
   private announceRowSelection(rowIndex: number, intent: SelectionIntent = 'replace') {
     const anchor = this.engine.getSelection().anchorRowIndex ?? rowIndex
+    if (intent === 'range' && this.engine.getConfig().selection.rowKey !== undefined) {
+      this.announceScreenReader(`${this.getDisplayedSelectedRowCount()} displayed rows selected.`)
+      return
+    }
     this.announceScreenReader(intent === 'range' && anchor !== rowIndex
       ? `Rows ${Math.min(anchor, rowIndex) + 1} through ${Math.max(anchor, rowIndex) + 1} selected.`
       : `Row ${rowIndex + 1} ${this.engine.isRowSelected(rowIndex) ? 'selected' : 'deselected'}.`)
@@ -1330,6 +1381,10 @@ export class DataGrid extends LitElement {
   }
 
   private announceVisibleRowCount(context: string) {
+    if (this.engine.getConfig().queryMode === 'external') {
+      this.announceScreenReader(`${context}. Server query requested.`)
+      return
+    }
     const rowCount = this.engine.getRowCount()
     this.announceScreenReader(rowCount === 0 ? `${context}. No matching rows.` : `${context}. ${rowCount} ${rowCount === 1 ? 'row' : 'rows'} shown.`)
   }
@@ -1337,22 +1392,25 @@ export class DataGrid extends LitElement {
 
 
   private handleSortAscending(columnKey: string) {
+    if (!this.getColumnCapabilities(columnKey).sortable) return
     this.engine.sortBy(columnKey, 'asc')
-    this.announceScreenReader(`${this.getColumnLabel(columnKey)} sorted ascending.`)
+    this.announceScreenReader(`${this.getColumnLabel(columnKey)} ${this.engine.getConfig().queryMode === 'external' ? 'ascending sort requested' : 'sorted ascending'}.`)
     this.requestUpdate()
     this.closeHeaderMenu(true)
   }
 
   private handleSortDescending(columnKey: string) {
+    if (!this.getColumnCapabilities(columnKey).sortable) return
     this.engine.sortBy(columnKey, 'desc')
-    this.announceScreenReader(`${this.getColumnLabel(columnKey)} sorted descending.`)
+    this.announceScreenReader(`${this.getColumnLabel(columnKey)} ${this.engine.getConfig().queryMode === 'external' ? 'descending sort requested' : 'sorted descending'}.`)
     this.requestUpdate()
     this.closeHeaderMenu(true)
   }
 
-  private handleClearSort() {
+  private handleClearSort(columnKey: string) {
+    if (!this.getColumnCapabilities(columnKey).sortable) return
     this.engine.clearSort()
-    this.announceScreenReader('Sorting cleared.')
+    this.announceScreenReader(this.engine.getConfig().queryMode === 'external' ? 'Clear sorting requested.' : 'Sorting cleared.')
     this.requestUpdate()
     this.closeHeaderMenu(true)
   }
@@ -1560,7 +1618,8 @@ export class DataGrid extends LitElement {
     const threshold = Math.max(0, Math.floor(this.quickSearchDebounceThreshold))
     const debounceMs = Math.max(0, Math.floor(this.quickSearchDebounceMs))
 
-    if (this.sourceRowCount < threshold || debounceMs === 0) {
+    const external = this.engine.getConfig().queryMode === 'external'
+    if (debounceMs === 0 || (!external && this.sourceRowCount < threshold)) {
       this.applyQuickSearch(query)
       return
     }
@@ -1596,19 +1655,57 @@ export class DataGrid extends LitElement {
     return this.engine.getFilters()
   }
 
+  sortBy(columnKey: string, direction: SortDirection) {
+    this.engine.sortBy(columnKey, direction)
+    this.resetVerticalScroll()
+    this.requestUpdate()
+  }
+
+  clearSort() {
+    this.engine.clearSort()
+    this.resetVerticalScroll()
+    this.requestUpdate()
+  }
+
+  getQuery() { return this.engine.getQuery() }
+  refreshQuery() { this.engine.refreshQuery() }
+  get externalState() { return this.engine.getExternalState() }
+  set externalState(value: GridExternalState | null) {
+    if (value) this.setExternalState(value)
+  }
+  setExternalState(value: GridExternalState): boolean {
+    if (!this.engine.setExternalState(value)) return false
+    this.clearQuickSearchDebounce()
+    this.quickSearchDraft = this.engine.getQuickSearch()
+    this.filterDrafts = new Map(this.engine.getFilters().map(filter => [filter.columnKey, filter]))
+    this.sourceRowCount = this.engine.getRowCount()
+    this.clearBestFitWidths()
+    this.requestUpdate()
+    return true
+  }
+
+  private getPageLabel() {
+    const pagination = this.engine.getPagination()
+    if (this.engine.getConfig().queryMode === 'external' && pagination.totalKnown && pagination.pageIndex > 0 && pagination.pageIndex >= pagination.pageCount) return `Page ${pagination.pageIndex + 1} (out of range)`
+    return pagination.totalKnown === false ? `Page ${pagination.pageIndex + 1}`
+      : `Page ${pagination.pageCount === 0 ? 0 : pagination.pageIndex + 1} of ${pagination.pageCount}`
+  }
+
   setPage(pageIndex: number) {
+    this.rememberPaginationFocus()
     this.engine.setPage(pageIndex)
     this.resetVerticalScroll()
     const pagination = this.engine.getPagination()
-    this.announceScreenReader(`Page ${pagination.pageCount === 0 ? 0 : pagination.pageIndex + 1} of ${pagination.pageCount}.`)
+    this.announceScreenReader(`${this.getPageLabel()}.`)
     this.requestUpdate()
   }
 
   setPageSize(pageSize: number) {
+    this.rememberPaginationFocus()
     this.engine.setPageSize(pageSize)
     this.resetVerticalScroll()
     const pagination = this.engine.getPagination()
-    this.announceScreenReader(`${pagination.pageSize} rows per page. Page ${pagination.pageCount === 0 ? 0 : pagination.pageIndex + 1} of ${pagination.pageCount}.`)
+    this.announceScreenReader(`${pagination.pageSize} rows per page. ${this.getPageLabel()}.`)
     this.requestUpdate()
   }
 
@@ -1616,6 +1713,11 @@ export class DataGrid extends LitElement {
     return this.engine.getPagination()
   }
 
+  private rememberPaginationFocus() {
+    const active = this.shadowRoot?.activeElement
+    if (active instanceof HTMLButtonElement && active.closest('.pagination')) this.paginationFocusTarget = active
+  }
+
   getTotalRowCount() {
     return this.engine.getTotalRowCount()
   }
@@ -1634,11 +1736,17 @@ export class DataGrid extends LitElement {
     this.requestUpdate()
   }
 
+  private announceAllRowsSelected() {
+    const count = this.engine.getSelectableRowCount()
+    const qualifier = count === this.engine.getRowCount() ? '' : 'selectable '
+    this.announceScreenReader(`All ${count} ${qualifier}displayed rows selected.`)
+  }
+
   selectAllRows() {
-    if (this.engine.getConfig().selection.mode !== 'multi-row' || this.engine.getRowCount() === 0) return
-    const unchanged = this.engine.getSelection().rowIndexes.size === this.engine.getRowCount()
+    if (this.engine.getConfig().selection.mode !== 'multi-row' || this.engine.getSelectableRowCount() === 0) return
+    const unchanged = this.engine.getSelection().rowIndexes.size === this.engine.getSelectableRowCount()
     this.engine.selectAllRows()
-    if (!unchanged) this.announceScreenReader(`All ${this.engine.getRowCount()} displayed rows selected.`)
+    if (!unchanged) this.announceAllRowsSelected()
     this.requestUpdate()
   }
 
@@ -1654,6 +1762,22 @@ export class DataGrid extends LitElement {
     return this.engine.getSelection()
   }
 
+  getSelectionSnapshot(): SelectionChangeDetail {
+    return this.engine.getSelectionSnapshot()
+  }
+
+  selectRowByKey(key: GridRowKey, intent?: SelectionIntent): boolean {
+    const previous = this.engine.getSelectionSnapshot()
+    const selected = this.engine.selectRowByKey(key, intent)
+    const next = this.engine.getSelectionSnapshot()
+    if (selected && next !== previous) {
+      const index = next.rows.find(row => row.key === key)?.rowIndex
+        ?? previous.rows.find(row => row.key === key)?.rowIndex
+      if (index !== undefined) this.announceRowSelection(index, intent)
+    }
+    return selected
+  }
+
   isRowSelected(rowIndex: number) {
     return this.engine.isRowSelected(rowIndex)
   }
@@ -1713,6 +1837,7 @@ export class DataGrid extends LitElement {
   }
 
   private applyHeaderFilter(columnKey: string) {
+    if (!this.getColumnCapabilities(columnKey).filterable) return
     const filter = this.getFilterDraft(columnKey)
     this.setFilter({
       ...filter,
@@ -1722,6 +1847,7 @@ export class DataGrid extends LitElement {
   }
 
   private clearHeaderFilter(columnKey: string) {
+    if (!this.getColumnCapabilities(columnKey).filterable) return
     this.clearFilter(columnKey)
     this.closeHeaderMenu(true)
   }
@@ -2534,6 +2660,7 @@ export class DataGrid extends LitElement {
   }
 
     set data(value: unknown[]) {
+    if (this.engine.getConfig().queryMode === 'external') return
     this.clearQuickSearchDebounce()
 
     this.sourceRowCount = Array.isArray(value) ? value.length : 0
@@ -2549,26 +2676,17 @@ export class DataGrid extends LitElement {
   }
 
   private getDisplayedSelectedRowCount() {
-    const rowCount = this.engine.getRowCount()
-    let selectedCount = 0
-
-    for (let rowIndex = 0; rowIndex < rowCount; rowIndex += 1) {
-      if (this.engine.isRowSelected(rowIndex)) {
-        selectedCount += 1
-      }
-    }
-
-    return selectedCount
+    return this.engine.getSelectionSnapshot().rowIndexes.length
   }
 
   private areAllDisplayedRowsSelected() {
-    const rowCount = this.engine.getRowCount()
+    const rowCount = this.engine.getSelectableRowCount()
     return rowCount > 0 && this.getDisplayedSelectedRowCount() === rowCount
   }
 
   private hasPartiallySelectedDisplayedRows() {
     const selectedCount = this.getDisplayedSelectedRowCount()
-    return selectedCount > 0 && selectedCount < this.engine.getRowCount()
+    return selectedCount > 0 && selectedCount < this.engine.getSelectableRowCount()
   }
 
   private handleSelectAllRows() {
@@ -2577,7 +2695,7 @@ export class DataGrid extends LitElement {
       this.announceScreenReader('All displayed rows deselected.')
     } else {
       this.engine.selectAllRows()
-      this.announceScreenReader(`All ${this.engine.getRowCount()} displayed rows selected.`)
+      this.announceAllRowsSelected()
     }
     this.requestUpdate()
   }
@@ -2758,6 +2876,12 @@ export class DataGrid extends LitElement {
   render() {
     const count = this.engine.getRowCount()
     const pagination = this.engine.getPagination()
+    const external = this.engine.getConfig().queryMode === 'external'
+    const externalState = external ? this.engine.getExternalState() : null
+    const outOfRange = external && pagination.totalKnown && pagination.pageIndex > 0 && pagination.pageIndex >= pagination.pageCount
+    const externalStatus = externalState?.loading ? 'Loading results.' : externalState?.error
+      ? externalState.error : outOfRange ? 'Requested page is out of range. Choose a previous page.'
+      : count === 0 ? (pagination.totalRows === 0 ? 'No results.' : 'No rows on this page.') : ''
     const pageSizeOptions = [25, 50, 100].includes(pagination.pageSize)
       ? [25, 50, 100]
       : [pagination.pageSize, 25, 50, 100].sort((left, right) => left - right)
@@ -2881,14 +3005,16 @@ export class DataGrid extends LitElement {
     return html`
             <div
         class="shell"
+        aria-busy=${external ? String(!!externalState?.loading) : nothing}
         style=${`--virtual-grid-template: ${gridTemplate}; --total-column-width: ${totalColumnWidth}px; --total-row-width: ${totalRowWidth}px; --row-header-width: ${rowHeaderWidth}px; --header-grid-template: ${headerGridTemplate}; --scrollbar-width: ${this.scrollbarWidth}px;`}
         @keydown=${this.handleShellKeyDown}
         >
         <p id=${`${this.gridId}-description`} class="screen-reader-only">${this.getScreenReaderDescription()}</p>
+        ${external && externalStatus ? html`<div class="external-status" role=${externalState?.error ? 'alert' : 'status'}>${externalStatus}</div>` : nothing}
         ${this.screenReaderAnnouncements
           ? html`<div class="screen-reader-only" role="status" aria-live="polite" aria-atomic="true">${this.screenReaderMessage}</div>`
           : ''}
-        ${this.quickSearchVisible
+        ${this.quickSearchVisible || external
           ? html`
               <div class="quick-search" role="search">
                 <input
@@ -2938,7 +3064,7 @@ export class DataGrid extends LitElement {
                         aria-label="Select all displayed rows"
                         .checked=${this.areAllDisplayedRowsSelected()}
                         .indeterminate=${this.hasPartiallySelectedDisplayedRows()}
-                        ?disabled=${this.engine.getRowCount() === 0}
+                        ?disabled=${this.engine.getSelectableRowCount() === 0}
                         @change=${() => this.handleSelectAllRows()}
                       />`
                     : html`<span>#</span>`}
@@ -3006,19 +3132,22 @@ export class DataGrid extends LitElement {
                                 ${this.quickSearchVisible ? 'Hide Quick Search' : 'Show Quick Search'}
                               </button>
                               <hr class="header-menu-divider" />
-                              <button type="button" @click=${() => this.handleSortAscending(column.key)}>
-                                Sort Asc
-                              </button>
-                              <button type="button" @click=${() => this.handleSortDescending(column.key)}>
-                                Sort Desc
-                              </button>
-                                                            <button type="button" @click=${() => this.handleClearSort()}>
-                                                              Clear Sort
-                                                            </button>
+                              ${column.sortable === false ? '' : html`
+                                <button type="button" @click=${() => this.handleSortAscending(column.key)}>
+                                  Sort Asc
+                                </button>
+                                <button type="button" @click=${() => this.handleSortDescending(column.key)}>
+                                  Sort Desc
+                                </button>
+                                <button type="button" @click=${() => this.handleClearSort(column.key)}>
+                                  Clear Sort
+                                </button>
+                              `}
                                                             <button type="button" @click=${(event: MouseEvent) => this.toggleColumnChooser(event)}>
                                                               Columns
                                                             </button>
                               ${(() => {
+                                if (column.filterable === false) return ''
                                 const draft = this.getFilterDraft(column.key)
                                 const valueFree = this.isValueFreeFilter(draft.operator)
 
@@ -3146,7 +3275,7 @@ export class DataGrid extends LitElement {
           ? html`
               <div class="pagination" role="navigation" aria-label="Pagination">
                 <div class="pagination-summary">
-                  <span>${pagination.totalRows} rows</span>
+                  <span>${pagination.totalKnown === false ? 'Total unknown' : `${pagination.totalRows} rows`}</span>
                   <label>
                     Rows per page
                     <select
@@ -3163,7 +3292,7 @@ export class DataGrid extends LitElement {
                   </label>
                 </div>
                 <div class="pagination-navigation">
-                  <span>Page ${pagination.pageCount === 0 ? 0 : pagination.pageIndex + 1} of ${pagination.pageCount}</span>
+                  <span>${this.getPageLabel()}</span>
                   <button
                     type="button"
                     ?disabled=${pagination.pageIndex === 0}
@@ -3171,7 +3300,7 @@ export class DataGrid extends LitElement {
                   >Previous</button>
                   <button
                     type="button"
-                    ?disabled=${pagination.pageCount === 0 || pagination.pageIndex >= pagination.pageCount - 1}
+                    ?disabled=${pagination.totalKnown === false ? !pagination.hasMore : pagination.pageCount === 0 || pagination.pageIndex >= pagination.pageCount - 1}
                     @click=${() => this.setPage(pagination.pageIndex + 1)}
                   >Next</button>
                 </div>

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './components/DataGrid.js'
+export type { GridQuery, GridQueryFilter, GridQueryReason, GridQueryChangeDetail, GridQuerySnapshot, GridExternalTotal, GridExternalState, SortDirection } from './types.js'
 export type {
   BestFitColumnWidth,
   ColumnReorderDetail,
@@ -8,6 +9,9 @@ export type {
   GridFilter,
   GridPaginationState,
   GridSelection,
+  GridRowKey,
+  SelectedRowSnapshot,
+  SelectionChangeDetail,
   SelectionIntent,
   GridColumn,
   GridTheme,

package/src/types.ts

@@ -3,13 +3,23 @@ import type {
   GridFilter,
   GridPaginationState,
   GridSelection,
+  GridRowKey,
+  SelectionChangeDetail,
+  GridExternalState,
+  GridQuerySnapshot,
+  GridQueryChangeDetail,
+  SortDirection,
   SelectionIntent
 } from '@tipolox/litgrid-core'
 import type { ColumnStateChangeDetail, GridColumnState } from './columnState/columnState.js'
 
 export type { ColumnStateChangeDetail, GridColumnState }
+export type { GridQuery, GridQueryFilter, GridQueryReason, GridQueryChangeDetail, GridQuerySnapshot, GridExternalTotal, GridExternalState, SortDirection } from '@tipolox/litgrid-core'
 
 export type {
+  GridRowKey,
+  SelectedRowSnapshot,
+  SelectionChangeDetail,
   GridConfig,
   GridFilter,
   GridPaginationState,
@@ -24,6 +34,10 @@ export type GridColumn = {
   header?: string
   width?: number | string
   hidden?: boolean
+  /** Show local sorting actions in the header menu. Defaults to true; does not change query state or imperative APIs. */
+  sortable?: boolean
+  /** Show local column filtering controls. Defaults to true; does not affect quick search or imperative APIs. */
+  filterable?: boolean
   accessor?: (row: unknown, rowIndex: number) => unknown
   render?: (value: unknown, row: unknown, rowIndex: number) => unknown
 }
@@ -47,6 +61,13 @@ export type ColumnVisibilityChangeDetail = {
 }
 
 export type DataGridElement = HTMLElement & {
+  /** Additive external-query capabilities; production DataGrid implements them. */
+  externalState?: GridExternalState | null
+  setExternalState?: (state: GridExternalState) => boolean
+  getQuery?: () => GridQuerySnapshot
+  refreshQuery?: () => void
+  sortBy?: (columnKey: string, direction: SortDirection) => void
+  clearSort?: () => void
   data: unknown[]
   columns: GridColumn[]
   config: GridConfig
@@ -103,6 +124,15 @@ export type DataGridElement = HTMLElement & {
   selectAllRows: () => void
   clearSelection: () => void
   getSelection: () => GridSelection
+  getSelectionSnapshot: () => SelectionChangeDetail
+  selectRowByKey: (key: GridRowKey, intent?: SelectionIntent) => boolean
   isRowSelected: (rowIndex: number) => boolean
   isCellSelected: (rowIndex: number, columnKey: string) => boolean
 }
+
+declare global {
+  interface HTMLElementEventMap {
+    'selection-change': CustomEvent<SelectionChangeDetail>
+    'query-change': CustomEvent<GridQueryChangeDetail>
+  }
+}