@warkypublic/svelix 0.1.28 → 0.1.31

package/dist/components/Boxer/Boxer.svelte

@@ -97,6 +97,7 @@
   let dropdownZ = $state(1100);
   let pointerInteractingWithDropdown = $state(false);
   let insideDialog = $state(false);
+  let suppressOpenOnFocus = $state(false);
   const effectiveDisablePortal = $derived(disablePortal || insideDialog);
   // Plain variable — NOT $state to avoid deep proxy on the complex virtualizer object.
   let rawVirtualizer: SvelteVirtualizer<
@@ -303,6 +304,12 @@
           activeOptionIndex = null;
         }
         break;
+      case "Tab":
+        if (multiSelect && $store.opened && $store.boxerData.length > 0) {
+          e.preventDefault();
+          onOptionSubmit(0);
+        }
+        break;
     }
   }
 
@@ -331,6 +338,7 @@
         e.preventDefault();
         store.setOpened(false);
         activeOptionIndex = null;
+        suppressOpenOnFocus = true;
         targetRef?.focus();
         break;
     }
@@ -387,6 +395,7 @@
     activeOptionIndex = null;
   }
   export function focus() {
+    suppressOpenOnFocus = false;
     targetRef?.focus();
   }
   export function getValue() {
@@ -504,7 +513,13 @@
     isFetching={$store.isFetching}
     search={$store.input}
     onclear={onClear}
-    onfocus={() => store.setOpened(true)}
+    onfocus={() => {
+      if (suppressOpenOnFocus) {
+        suppressOpenOnFocus = false;
+        return;
+      }
+      store.setOpened(true);
+    }}
     onkeydown={onInputKeydown}
     onsearch={(v) => {
       store.setSearch(v);

package/dist/components/Gridler/adapters/GridlerResolveSpecAdapter.d.ts

@@ -6,5 +6,5 @@ export declare class GridlerResolveSpecAdapter {
     private readonly entity;
     readonly uniqueID: string;
     constructor(config: GridlerAdapterConfig);
-    readPage(limit: number, cursorForward?: string, sort?: SortOption[], filters?: FilterOption[], extraOptions?: Partial<Options>): Promise<GridlerPageResult>;
+    readPage(limit: number, cursorForward?: string, sort?: SortOption[], filters?: FilterOption[], fields?: string[], extraOptions?: Partial<Options>): Promise<GridlerPageResult>;
 }

package/dist/components/Gridler/adapters/GridlerResolveSpecAdapter.js

@@ -11,13 +11,14 @@ export class GridlerResolveSpecAdapter {
         this.entity = config.entity;
         this.uniqueID = config.uniqueID ?? 'id';
     }
-    async readPage(limit, cursorForward, sort, filters, extraOptions) {
+    async readPage(limit, cursorForward, sort, filters, fields, extraOptions) {
         const options = {
             ...extraOptions,
             sort: sort ?? extraOptions?.sort ?? [],
             filters: filters ?? extraOptions?.filters ?? [],
             limit,
             ...(cursorForward != null ? { cursor_forward: cursorForward } : {}),
+            ...(fields?.length ? { columns: fields } : {}),
         };
         const response = await this.client.read(this.schema, this.entity, undefined, options);
         const rows = Array.isArray(response?.data) ? response.data : [];

package/dist/components/Gridler/adapters/GridlerRestHeaderSpecAdapter.d.ts

@@ -6,5 +6,5 @@ export declare class GridlerRestHeaderSpecAdapter {
     private readonly entity;
     readonly uniqueID: string;
     constructor(config: GridlerAdapterConfig);
-    readPage(limit: number, cursorForward?: string, sort?: SortOption[], filters?: FilterOption[], extraOptions?: Partial<Options>): Promise<GridlerPageResult>;
+    readPage(limit: number, cursorForward?: string, sort?: SortOption[], filters?: FilterOption[], fields?: string[], extraOptions?: Partial<Options>): Promise<GridlerPageResult>;
 }

package/dist/components/Gridler/adapters/GridlerRestHeaderSpecAdapter.js

@@ -11,13 +11,14 @@ export class GridlerRestHeaderSpecAdapter {
         this.entity = config.entity;
         this.uniqueID = config.uniqueID ?? 'id';
     }
-    async readPage(limit, cursorForward, sort, filters, extraOptions) {
+    async readPage(limit, cursorForward, sort, filters, fields, extraOptions) {
         const options = {
             ...extraOptions,
             sort: sort ?? extraOptions?.sort ?? [],
             filters: filters ?? extraOptions?.filters ?? [],
             limit,
             ...(cursorForward != null ? { cursor_forward: cursorForward } : {}),
+            ...(fields?.length ? { columns: fields } : {}),
         };
         const response = await this.client.read(this.schema, this.entity, undefined, options);
         const rows = Array.isArray(response?.data) ? response.data : [];

package/dist/components/Gridler/components/Gridler.svelte

@@ -28,6 +28,8 @@
       item?: Record<string, unknown>;
       column?: GridlerColumn;
     }) => void;
+    /** Resolve raw row data by row index for populating onCellEvent. */
+    getRowData?: (row: number) => Record<string, unknown> | undefined;
     children?: Snippet;
   }
 
@@ -68,8 +70,9 @@
     sortOrder,
     onFilterChange: _onFilterChange,
     filters: _filters,
-    selectedItems: _selectedItems,
+    selectedItems,
     onSelectedItemsChange: _onSelectedItemsChange,
+    getRowData,
     settings,
     children,
   }: Props = $props();
@@ -245,6 +248,7 @@
 
   function handleKeyDown(e: KeyboardEvent) {
     if (!canvasComponent?.getHasFocus()) return;
+    onGridEvent?.("keydown", undefined, undefined, { x: 0, y: 0, code: e.key });
 
     // Search toggle
     if ((e.ctrlKey || e.metaKey) && e.key === "f") {
@@ -308,7 +312,7 @@
         if (!resolvedReadonly) {
           beginEdit(focusedCell);
         }
-        onCellEvent?.("enter_key", {}, columns[col] ?? { id: "", title: "" });
+        onCellEvent?.("enter_key", getRowData?.(row) ?? {}, columns[col] ?? { id: "", title: "" });
         e.preventDefault();
         return;
       case "Escape": {
@@ -334,7 +338,7 @@
             onRowAppended?.();
           }
         }
-        onCellEvent?.("tab_key", {}, columns[col] ?? { id: "", title: "" });
+        onCellEvent?.("tab_key", getRowData?.(row) ?? {}, columns[col] ?? { id: "", title: "" });
         e.preventDefault();
         break;
       case "Delete":
@@ -346,7 +350,7 @@
             onDelete?.(delSel);
           }
         }
-        onCellEvent?.("delte_key", {}, columns[col] ?? { id: "", title: "" });
+        onCellEvent?.("delete_key", getRowData?.(row) ?? {}, columns[col] ?? { id: "", title: "" });
         return;
       }
       default:
@@ -376,7 +380,7 @@
 
   function handleVisibleRangeChange(range: VisibleRange) {
     onVisibleRangeChange?.(range);
-    onGridEvent?.("scroll", { row: range.firstRow, column: range.firstCol });
+    onGridEvent?.("scroll", undefined, undefined, undefined, { row: range.firstRow, column: range.firstCol });
   }
 
   async function handleMenuOpen(d: {
@@ -423,15 +427,45 @@
   onSelectionChange={(sel) => {
     currentSelection = sel;
     onSelectionChange?.(sel);
+    onGridEvent?.("selection_changed");
   }}
   onCellDblClick={(item, cell) => {
     onCellDblClick?.(item, cell);
-    onCellEvent?.("dblclick", {}, columns[item[0]] ?? { id: "", title: "" });
+    onCellEvent?.("dblclick", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" });
+    onGridEvent?.("dblclick", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" });
+  }}
+  onCellClick={(item) => {
+    onCellEvent?.("click", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" });
+    onGridEvent?.("click", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" });
+  }}
+  onCellHover={(item) => {
+    onCellEvent?.("hover", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" });
+    onGridEvent?.("hover", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" });
+  }}
+  onCellLeave={(item) => {
+    onCellEvent?.("leave", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" });
+    onGridEvent?.("leave", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" });
+  }}
+  onCellContextMenu={(item, x, y) => {
+    onCellEvent?.("contextmenu", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" }, { x, y });
+    onGridEvent?.("contextmenu", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" }, { x, y });
+  }}
+  onColumnResized={(col, width) => {
+    onGridEvent?.("column_resized", undefined, columns[col], undefined, { width });
+  }}
+  onGridResize={(width, height) => {
+    onGridEvent?.("resize", undefined, undefined, undefined, { width, height });
+  }}
+  onGridEnter={() => {
+    onGridEvent?.("enter");
   }}
   {sortOrder}
   {onSortOrderChange}
   {onHeaderContextMenu}
-  {onColumnMoved}
+  onColumnMoved={onColumnMoved || onGridEvent ? (from, to) => {
+    onColumnMoved?.(from, to);
+    onGridEvent?.("column_moved", undefined, undefined, undefined, { from, to });
+  } : undefined}
   {onCellEdited}
   {onDelete}
   {onRowAppended}

package/dist/components/Gridler/components/Gridler.svelte.d.ts

@@ -13,6 +13,8 @@ export interface Props extends Partial<GridlerProps> {
         item?: Record<string, unknown>;
         column?: GridlerColumn;
     }) => void;
+    /** Resolve raw row data by row index for populating onCellEvent. */
+    getRowData?: (row: number) => Record<string, unknown> | undefined;
     children?: Snippet;
 }
 declare const Gridler: import("svelte").Component<Props, {}, "">;

package/dist/components/Gridler/components/GridlerCanvas.svelte

@@ -72,6 +72,13 @@
       item?: Record<string, unknown>;
       column?: GridColumn<Record<string, unknown>>;
     }) => void;
+    onCellClick?: (item: Item) => void;
+    onCellHover?: (item: Item) => void;
+    onCellLeave?: (item: Item) => void;
+    onCellContextMenu?: (item: Item, x: number, y: number) => void;
+    onColumnResized?: (col: number, width: number) => void;
+    onGridResize?: (width: number, height: number) => void;
+    onGridEnter?: () => void;
     onkeydown?: (e: KeyboardEvent) => void;
     children?: Snippet;
   }
@@ -111,6 +118,13 @@
     onSearchValueChange,
     onSearchClose,
     onGridMenuOpen,
+    onCellClick,
+    onCellHover,
+    onCellLeave,
+    onCellContextMenu,
+    onColumnResized,
+    onGridResize,
+    onGridEnter,
     onkeydown,
     children,
   }: Props = $props();
@@ -133,6 +147,7 @@
   let hasFocus = $state(false);
   const gridId = `gridler-${Math.random().toString(36).slice(2, 10)}`;
 
+  let hoveredCell = $state<Item | null>(null);
   let isDraggingVScrollbar = $state(false);
   let isDraggingHScrollbar = $state(false);
   let vScrollDragStartY = $state(0);
@@ -286,6 +301,7 @@
       if (entry) {
         containerWidth = entry.contentRect.width;
         containerHeight = entry.contentRect.height;
+        onGridResize?.(entry.contentRect.width, entry.contentRect.height);
       }
     });
     observer.observe(containerRef);
@@ -468,8 +484,7 @@
   // ── Header context menu ───────────────────────────────────────────────────────
 
   function handleContextMenu(e: MouseEvent) {
-    if (!onHeaderContextMenu) return;
-    if (e.offsetY >= headerHeight || e.offsetX < rowMarkerWidth) return;
+    if (e.offsetX < rowMarkerWidth) return;
     const fixedBoundaryX =
       fixedColumns > 0
         ? getColumnX(effectiveColumns, Math.min(fixedColumns, columns.length))
@@ -477,10 +492,31 @@
     const localX = e.offsetX - rowMarkerWidth;
     const effectiveScrollX =
       fixedColumns > 0 && localX >= 0 && localX < fixedBoundaryX ? 0 : scrollX;
-    const col = getColumnFromX(localX + effectiveScrollX, effectiveColumns);
-    if (col >= 0 && col < columns.length) {
-      e.preventDefault();
-      onHeaderContextMenu(col, e.clientX, e.clientY);
+
+    if (e.offsetY < headerHeight) {
+      if (!onHeaderContextMenu) return;
+      const col = getColumnFromX(localX + effectiveScrollX, effectiveColumns);
+      if (col >= 0 && col < columns.length) {
+        e.preventDefault();
+        onHeaderContextMenu(col, e.clientX, e.clientY);
+      }
+      return;
+    }
+
+    if (onCellContextMenu) {
+      const cell = getCellFromPoint(
+        localX,
+        e.offsetY,
+        effectiveScrollX,
+        scrollY,
+        effectiveColumns,
+        rowHeight,
+        headerHeight,
+      );
+      if (cell) {
+        e.preventDefault();
+        onCellContextMenu(cell, e.clientX, e.clientY);
+      }
     }
   }
 
@@ -619,6 +655,7 @@
     }
 
     if (cell) {
+      onCellClick?.(cell);
       if (e.shiftKey && focusedCell) {
         const newSelection: Selection = {
           type: "range",
@@ -802,6 +839,36 @@
       return;
     }
 
+    // Hover cell tracking
+    if (e.offsetY >= headerHeight && e.offsetX >= rowMarkerWidth) {
+      const hoverFixedBoundaryX =
+        fixedColumns > 0
+          ? getColumnX(effectiveColumns, Math.min(fixedColumns, columns.length))
+          : 0;
+      const hoverLocalX = e.offsetX - rowMarkerWidth;
+      const hoverScrollX =
+        fixedColumns > 0 && hoverLocalX >= 0 && hoverLocalX < hoverFixedBoundaryX
+          ? 0
+          : scrollX;
+      const hoverCell = getCellFromPoint(
+        hoverLocalX,
+        e.offsetY,
+        hoverScrollX,
+        scrollY,
+        effectiveColumns,
+        rowHeight,
+        headerHeight,
+      );
+      if (hoverCell?.[0] !== hoveredCell?.[0] || hoverCell?.[1] !== hoveredCell?.[1]) {
+        if (hoveredCell) onCellLeave?.(hoveredCell);
+        hoveredCell = hoverCell;
+        if (hoverCell) onCellHover?.(hoverCell);
+      }
+    } else if (hoveredCell !== null) {
+      onCellLeave?.(hoveredCell);
+      hoveredCell = null;
+    }
+
     if (!isDragging || !dragStart) return;
 
     const fixedBoundaryX =
@@ -865,6 +932,9 @@
       scheduleDraw();
     }
 
+    if (resizingColumn !== null) {
+      onColumnResized?.(resizingColumn, columns[resizingColumn].width);
+    }
     isDragging = false;
     dragStart = null;
     resizingColumn = null;
@@ -876,6 +946,10 @@
     hoverResizeCol = null;
     hoverMenuButton = false;
     hoverSortCol = null;
+    if (hoveredCell) {
+      onCellLeave?.(hoveredCell);
+      hoveredCell = null;
+    }
     if (!isDraggingVScrollbar && !isDraggingHScrollbar) {
       handleMouseUp(e);
     } else {
@@ -1073,6 +1147,7 @@
   style:--gridler-header-height={`${headerHeight}px`}
   onfocusin={handleFocusIn}
   onfocusout={handleFocusOut}
+  onmouseenter={onGridEnter}
   {onkeydown}
 >
   <canvas

package/dist/components/Gridler/components/GridlerCanvas.svelte.d.ts

@@ -41,6 +41,13 @@ interface Props {
         item?: Record<string, unknown>;
         column?: GridColumn<Record<string, unknown>>;
     }) => void;
+    onCellClick?: (item: Item) => void;
+    onCellHover?: (item: Item) => void;
+    onCellLeave?: (item: Item) => void;
+    onCellContextMenu?: (item: Item, x: number, y: number) => void;
+    onColumnResized?: (col: number, width: number) => void;
+    onGridResize?: (width: number, height: number) => void;
+    onGridEnter?: () => void;
     onkeydown?: (e: KeyboardEvent) => void;
     children?: Snippet;
 }

package/dist/components/Gridler/components/GridlerFull.svelte

@@ -199,9 +199,11 @@
     if (typeof data === "function") {
       data().then((result) => {
         dataState = result;
+        onGridEvent?.("load");
       });
     } else {
       dataState = data.slice();
+      onGridEvent?.("load");
     }
   });
 
@@ -258,6 +260,7 @@
       internalSearchValue = value;
     }
     onSearchValueChange?.(value);
+    onGridEvent?.("search_changed", undefined, undefined, undefined, { searchValue: value });
   }
 
   // ── Context menu ───────────────────────────────────────────────────────────
@@ -477,6 +480,7 @@
   function handleFilterChange(next: GridColumnFilters) {
     if (filters === undefined) internalFilters = next;
     onFilterChange?.(next);
+    onGridEvent?.("filter_changed", undefined, undefined, undefined, { filters: next });
   }
 
 
@@ -513,6 +517,15 @@
     return [...base, ...buildSearchFilters(search, columnsState, searchColumns)];
   }
 
+  // Compute column fields (dataKey ?? id) merged with hotfields, deduped.
+  const resolvedFields = $derived.by(() => {
+    const columnFields = columnsState.map((c) => c.dataKey ?? c.id);
+    const hotfields = dataSourceOptions?.hotfields ?? [];
+    const seen = new Set(columnFields);
+    const extra = hotfields.filter((f) => !seen.has(f));
+    return [...columnFields, ...extra];
+  });
+
   // ── Sort state (controlled or internal) ───────────────────────────────────
 
   let internalSortOrder = $state<GridColumnSortOrder>({});
@@ -521,6 +534,7 @@
   function handleSortOrderChange(order: GridColumnSortOrder) {
     if (sortOrder === undefined) internalSortOrder = order;
     onSortOrderChange?.(order);
+    onGridEvent?.("sort_changed", undefined, undefined, undefined, { sortOrder: order });
   }
 
   const resolvedSort = $derived(
@@ -561,7 +575,7 @@
     const allFilters = buildAllFilters(_search);
 
     _adapter
-      .readPage(_pageSize, undefined, _sort, allFilters)
+      .readPage(_pageSize, undefined, _sort, allFilters, resolvedFields)
       .then((result) => {
         if (cancelled) return;
         serverData = result.data;
@@ -604,11 +618,13 @@
         cursorSnapshot,
         resolvedSort,
         allFilters,
+        resolvedFields,
       );
       if (serverData.length !== lengthSnapshot) return;
       serverData = [...serverData, ...result.data];
       serverCursor = result.nextCursor;
       serverAllLoaded = result.data.length < pageSize || !result.nextCursor;
+      onGridEvent?.("page_loaded", undefined, undefined, undefined, { data: result.data, total: serverData.length });
     } catch {
       // Silent — don't clobber existing rows with an error on append.
     } finally {
@@ -642,16 +658,39 @@
 
   // ── Selection → selectedItems bridge ──────────────────────────────────────
 
+  let internalSelectedItems = $state<Record<string, unknown>[]>([]);
+
   function handleSelectionChange(sel: Selection) {
-    if (sel.type === "row" && onSelectedItemsChange) {
-      const items = sel.rows
+    let items: Record<string, unknown>[] = [];
+    if (sel.type === "row") {
+      items = sel.rows
         .map((i) => resolveRowData(i))
         .filter((r): r is Record<string, unknown> => r !== undefined);
-      onSelectedItemsChange(items);
+    } else if (sel.type === "cell") {
+      const row = resolveRowData(sel.item[1]);
+      if (row) items = [row];
+    } else if (sel.type === "range") {
+      const minRow = Math.min(sel.start[1], sel.end[1]);
+      const maxRow = Math.max(sel.start[1], sel.end[1]);
+      for (let i = minRow; i <= maxRow; i++) {
+        const row = resolveRowData(i);
+        if (row) items.push(row);
+      }
     }
+    internalSelectedItems = items;
+    if (items.length > 0) onSelectedItemsChange?.(items);
     onSelectionChange?.(sel);
   }
 
+  // ── Settings change event ─────────────────────────────────────────────────
+
+  let lastSettings = $state(settings);
+  $effect(() => {
+    if (settings === untrack(() => lastSettings)) return;
+    lastSettings = settings;
+    onGridEvent?.("settings_changed", undefined, undefined, undefined, { settings });
+  });
+
   // ── Cell content ───────────────────────────────────────────────────────────
 
   const serverGetCellContent = $derived(makeGetCellContent(serverData, columnsState));
@@ -690,6 +729,7 @@
     };
     dataState = next;
     await onDataChange?.(next);
+    onGridEvent?.("data_changed", next[originalIndex], columnsState[col], undefined, { data: next });
   }
 
   async function handleGridMenuClick(d?: {
@@ -737,7 +777,10 @@
       onCellEdited?.(item, value);
     }}
     onCellDblClick={handleCellDblClick}
+    selectedItems={internalSelectedItems}
+    getRowData={resolveRowData}
     onSelectionChange={handleSelectionChange}
+    {onMenuClick}
     onGridMenuOpen={handleGridMenuClick}
     sortOrder={resolvedSortOrder}
     onSortOrderChange={handleSortOrderChange}

package/dist/components/Types/generic_grid.d.ts

@@ -71,6 +71,7 @@ export interface GridCommonProps<RowDataType = unknown, CellType = unknown> {
         entity?: string;
         uniqueID?: string;
         headers?: Record<string, string>;
+        hotfields?: string[];
     };
     data?: RowDataType[] | (() => Promise<RowDataType[]>);
     onDataChange?: (data: RowDataType[]) => Promise<void>;

package/llm/README.md

@@ -16,6 +16,7 @@ This folder contains AI-readable documentation that ships with the package.
 - [tools/SVAR.md](./tools/SVAR.md)
 - [tools/resolvespec-js.md](./tools/resolvespec-js.md)
 - [plans/canvasgrid.md](./plans/canvasgrid.md)
+- [gridler-events.md](./gridler-events.md)
 
 ## Installed package paths
 

package/llm/gridler-events.md

@@ -0,0 +1,139 @@
+# Gridler Events
+
+`GridlerFull` (and the lower-level `Gridler`) emit two event callbacks defined in `GridCommonProps` (`src/lib/components/Types/generic_grid.ts`):
+
+| Callback | Purpose |
+|---|---|
+| `onGridEvent` | Grid-level events (interaction, state, lifecycle) |
+| `onCellEvent` | Cell-level events (mouse + keyboard on a specific cell) |
+
+---
+
+## `onGridEvent`
+
+```ts
+onGridEvent?: (
+  type: GridEventType,
+  item?: Record<string, unknown>,   // resolved raw row data
+  column?: GridColumn,
+  coords?: GridEventCoords,          // { x, y, code? }
+  detail?: GridEventDetail,          // event-specific payload
+) => void
+```
+
+### All `GridEventType` values
+
+| Type | Fired from | `item` | `column` | `coords` | `detail` |
+|---|---|---|---|---|---|
+| `click` | Mouse click on a cell | row data | clicked column | — | — |
+| `dblclick` | Double-click on a cell | row data | clicked column | — | — |
+| `contextmenu` | Right-click on a cell | row data | clicked column | `{ x, y }` client coords | — |
+| `keydown` | Any key pressed while grid focused | — | — | `{ x:0, y:0, code }` | — |
+| `hover` | Mouse moves over a new cell | row data | hovered column | — | — |
+| `leave` | Mouse leaves a cell | row data | vacated column | — | — |
+| `enter` | Mouse enters the grid container | — | — | — | — |
+| `load` | Local `data` prop set/changed, or first server page loaded | — | — | — | — |
+| `scroll` | Visible range changes (scroll) | — | — | — | `{ row, column }` first visible |
+| `resize` | Grid container resized (ResizeObserver) | — | — | — | `{ width, height }` |
+| `page_loaded` | Next cursor page loaded from server | — | — | — | `{ data, total }` |
+| `sort_changed` | Sort order applied or cleared | — | — | — | `{ sortOrder: GridColumnSortOrder }` |
+| `filter_changed` | Filter applied or cleared | — | — | — | `{ filters: GridColumnFilters }` |
+| `search_changed` | Search input value changed | — | — | — | `{ searchValue: string }` |
+| `selection_changed` | Cell, row, range, or column selection changes | — | — | — | — |
+| `column_moved` | Column dragged to new position | — | — | — | `{ from: number, to: number }` |
+| `column_resized` | Column edge dragged to new width | — | moved column | — | `{ width: number }` |
+| `data_changed` | Cell edited and committed (local mode only) | updated row | edited column | — | `{ data: Row[] }` full new dataset |
+| `settings_changed` | `settings` prop reference changed | — | — | — | `{ settings }` |
+
+---
+
+## `onCellEvent`
+
+```ts
+onCellEvent?: (
+  type: GridCellEventType,
+  item: Record<string, unknown>,  // resolved raw row data
+  column: GridColumn,
+  coords?: GridEventCoords,
+  detail?: GridEventDetail,
+) => void
+```
+
+### All `GridCellEventType` values
+
+| Type | Fired when |
+|---|---|
+| `click` | Mouse click on the cell |
+| `dblclick` | Double-click on the cell |
+| `contextmenu` | Right-click on the cell |
+| `hover` | Mouse moves over this cell |
+| `leave` | Mouse leaves this cell |
+| `enter_key` | Enter pressed while this cell is focused |
+| `tab_key` | Tab pressed while this cell is focused |
+| `delete_key` | Delete or Backspace pressed while this cell is focused |
+
+For all `onCellEvent` calls, `item` carries the **resolved raw row data** (from `serverData` or local `filteredDataState`). When the row cannot be resolved by index (e.g. from a top-level menu button), `item` falls back to the value in `selectedItems[0]`.
+
+---
+
+## Row data resolution
+
+`GridlerFull` passes `getRowData` to `Gridler`, which calls `resolveRowData(rowIndex)`:
+
+```ts
+function resolveRowData(row: number): Record<string, unknown> | undefined {
+  return isServerMode ? serverData[row] : filteredDataState[row];
+}
+```
+
+The current selection's row data is also tracked in `internalSelectedItems` state and passed as `selectedItems` to `Gridler`. This is used as a fallback when no row index is available.
+
+---
+
+## Field selection sent to adapters (hotfields)
+
+When `dataSource="resolvespec"` or `"headerspec"`, `GridlerFull` derives a `resolvedFields` array and passes it to every `readPage` call as `options.columns` (maps to `X-Select-Fields` in headerspec):
+
+```ts
+const resolvedFields = $derived.by(() => {
+  const columnFields = columnsState.map((c) => c.dataKey ?? c.id);
+  const hotfields = dataSourceOptions?.hotfields ?? [];
+  const seen = new Set(columnFields);
+  const extra = hotfields.filter((f) => !seen.has(f));
+  return [...columnFields, ...extra];
+});
+```
+
+- **Column fields** come from `column.dataKey ?? column.id` for every column.
+- **Hotfields** (`dataSourceOptions.hotfields`) are extra fields needed server-side (for filtering, sorting, FK lookups) that are not grid columns. They are appended without duplicating existing column fields.
+
+---
+
+## Usage example
+
+```svelte
+<GridlerFull
+  {columns}
+  {data}
+  onGridEvent={(type, item, column, coords, detail) => {
+    if (type === 'sort_changed') console.log('Sort:', detail?.sortOrder);
+    if (type === 'filter_changed') console.log('Filter:', detail?.filters);
+    if (type === 'search_changed') console.log('Search:', detail?.searchValue);
+    if (type === 'data_changed') console.log('Edited row:', item, 'All data:', detail?.data);
+    if (type === 'column_moved') console.log('Moved col', detail?.from, '→', detail?.to);
+    if (type === 'page_loaded') console.log('New page:', detail?.data, 'Total so far:', detail?.total);
+  }}
+  onCellEvent={(type, item, column) => {
+    if (type === 'click') console.log('Clicked:', item, column.id);
+    if (type === 'enter_key') console.log('Enter on row:', item);
+  }}
+  dataSource="resolvespec"
+  dataSourceOptions={{
+    url: 'https://api.example.com',
+    schema: 'public',
+    entity: 'users',
+    uniqueID: 'id',
+    hotfields: ['tenant_id', 'deleted_at'],  // fetched but not shown as columns
+  }}
+/>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warkypublic/svelix",
-  "version": "0.1.28",
+  "version": "0.1.31",
   "description": "Svelte 5 component library with Skeleton UI and Tailwind CSS",
   "license": "Apache-2.0",
   "exports": {
@@ -26,43 +26,43 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.30.0",
-    "@chromatic-com/storybook": "^5.0.2",
-    "@eslint/compat": "^2.0.3",
+    "@chromatic-com/storybook": "^5.1.1",
+    "@eslint/compat": "^2.0.4",
     "@eslint/js": "^10.0.1",
-    "@playwright/test": "^1.58.2",
-    "@sentry/svelte": "^10.45.0",
-    "@skeletonlabs/skeleton": "^4.13.0",
-    "@skeletonlabs/skeleton-svelte": "^4.13.0",
-    "@storybook/addon-a11y": "^10.3.1",
-    "@storybook/addon-docs": "^10.3.1",
-    "@storybook/addon-svelte-csf": "^5.0.12",
-    "@storybook/addon-vitest": "^10.3.1",
-    "@storybook/sveltekit": "^10.3.1",
+    "@playwright/test": "^1.59.1",
+    "@sentry/svelte": "^10.47.0",
+    "@skeletonlabs/skeleton": "^4.15.1",
+    "@skeletonlabs/skeleton-svelte": "^4.15.1",
+    "@storybook/addon-a11y": "^10.3.4",
+    "@storybook/addon-docs": "^10.3.4",
+    "@storybook/addon-svelte-csf": "^5.1.2",
+    "@storybook/addon-vitest": "^10.3.4",
+    "@storybook/sveltekit": "^10.3.4",
     "@storybook/test": "^8.6.15",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.55.0",
+    "@sveltejs/kit": "^2.56.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.2.2",
     "@tanstack/svelte-virtual": "^3.13.23",
-    "@types/node": "^25.5.0",
-    "@vitest/browser-playwright": "^4.1.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "eslint": "^10.0.3",
-    "eslint-plugin-svelte": "^3.15.2",
+    "@types/node": "^25.5.2",
+    "@vitest/browser-playwright": "^4.1.3",
+    "@vitest/coverage-v8": "^4.1.3",
+    "eslint": "^10.2.0",
+    "eslint-plugin-svelte": "^3.17.0",
     "globals": "^17.4.0",
-    "playwright": "^1.58.2",
+    "playwright": "^1.59.1",
     "publint": "^0.3.18",
-    "storybook": "^10.3.1",
-    "svelte": "^5.54.0",
-    "svelte-check": "^4.4.5",
+    "storybook": "^10.3.4",
+    "svelte": "^5.55.1",
+    "svelte-check": "^4.4.6",
     "tailwindcss": "^4.2.2",
     "tslib": "^2.8.1",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.57.1",
-    "vite": "^8.0.1",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.0",
+    "vite": "^8.0.7",
     "vite-plugin-monaco-editor": "^1.1.0",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.3"
   },
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -76,13 +76,13 @@
     "@cartamd/plugin-math": "^4.3.1",
     "@friendofsvelte/tipex": "^0.1.1",
     "@js-temporal/polyfill": "^0.5.1",
-    "@svar-ui/svelte-grid": "^2.6.0",
+    "@svar-ui/svelte-grid": "^2.6.1",
     "@warkypublic/resolvespec-js": "^1.0.1",
     "@warkypublic/artemis-kit": "^1.0.10",
     "carta-md": "^4.11.1",
     "github-markdown-css": "^5.9.0",
-    "isomorphic-dompurify": "^3.5.1",
-    "katex": "^0.16.39",
+    "isomorphic-dompurify": "^3.7.1",
+    "katex": "^0.16.45",
     "monaco-editor": "^0.55.1"
   },
   "scripts": {