@warkypublic/svelix 0.1.42 → 0.1.44

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

@@ -157,6 +157,29 @@
     cancelEdit();
   }
 
+  function getSelectionRowData(sel: Selection): Record<string, unknown>[] | undefined {
+    if (!getRowData) return undefined;
+    if (sel.type === "cell") {
+      const d = getRowData(sel.item[1]);
+      return d ? [d] : undefined;
+    }
+    if (sel.type === "row") {
+      const items = sel.rows.map(getRowData).filter((r): r is Record<string, unknown> => r !== undefined);
+      return items.length > 0 ? items : undefined;
+    }
+    if (sel.type === "range") {
+      const minRow = Math.min(sel.start[1], sel.end[1]);
+      const maxRow = Math.max(sel.start[1], sel.end[1]);
+      const items: Record<string, unknown>[] = [];
+      for (let i = minRow; i <= maxRow; i++) {
+        const d = getRowData(i);
+        if (d) items.push(d);
+      }
+      return items.length > 0 ? items : undefined;
+    }
+    return undefined;
+  }
+
   // ── Row toggle (checkbox / number markers) ────────────────────────────────────
 
   function handleRowToggle(row: number) {
@@ -173,7 +196,7 @@
     }
     currentSelection = newSel;
     canvasComponent?.setCurrentSelection(newSel);
-    onSelectionChange?.(newSel);
+    onSelectionChange?.(newSel, getSelectionRowData(newSel));
   }
 
   // ── Clipboard ────────────────────────────────────────────────────────────────
@@ -295,7 +318,7 @@
         };
         currentSelection = newSel;
         canvasComponent?.setCurrentSelection(newSel);
-        onSelectionChange?.(newSel);
+        onSelectionChange?.(newSel, getSelectionRowData(newSel));
         canvasComponent?.setAnnouncement("All cells selected");
       }
       e.preventDefault();
@@ -386,7 +409,7 @@
       const newSel: Selection = { type: "cell", item: newFocusedCell };
       currentSelection = newSel;
       canvasComponent?.setCurrentSelection(newSel);
-      onSelectionChange?.(newSel);
+      onSelectionChange?.(newSel, getSelectionRowData(newSel));
       canvasComponent?.setAnnouncement(
         `Row ${newRow + 1}, column ${columns[newCol]?.title ?? newCol + 1}`,
       );
@@ -445,7 +468,7 @@
   onVisibleRangeChange={handleVisibleRangeChange}
   onSelectionChange={(sel) => {
     currentSelection = sel;
-    onSelectionChange?.(sel);
+    onSelectionChange?.(sel, getSelectionRowData(sel));
     onGridEvent?.("selection_changed");
   }}
   onCellDblClick={(item, cell) => {

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

@@ -1137,6 +1137,7 @@
   style:--gridler-bg-header-focus={mergedTheme.bgHeaderHasFocus}
   style:--gridler-bg-search-result={mergedTheme.bgSearchResult}
   style:--gridler-header-height={`${headerHeight}px`}
+  style:--gridler-row-marker-width={`${rowMarkerWidth}px`}
   onfocusin={handleFocusIn}
   onfocusout={handleFocusOut}
   onmouseenter={onGridEnter}

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

@@ -758,7 +758,7 @@
     }
     internalSelectedItems = items;
     if (items.length > 0) onSelectedItemsChange?.(items);
-    onSelectionChange?.(sel);
+    onSelectionChange?.(sel, items.length > 0 ? items : undefined);
   }
 
   // ── Settings change event ─────────────────────────────────────────────────
@@ -970,7 +970,10 @@
   .gf-loading,
   .gf-error {
     position: absolute;
-    inset: 0;
+    top: var(--gridler-header-height, 36px);
+    left: var(--gridler-row-marker-width, 0px);
+    right: 0;
+    bottom: 0;
     display: flex;
     align-items: center;
     justify-content: center;

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

@@ -9,11 +9,11 @@
 
   const { value, onValueChange, onClose }: Props = $props();
 
-  let inputRef: HTMLInputElement | undefined = $state();
+  let inputRef: HTMLInputElement | undefined;
 
-  $effect(() => {
+  export function focus() {
     inputRef?.focus();
-  });
+  }
 </script>
 
 <div class="gridler-search" role="search">

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

@@ -3,6 +3,8 @@ interface Props {
     onValueChange: (v: string) => void;
     onClose?: () => void;
 }
-declare const GridlerSearch: import("svelte").Component<Props, {}, "">;
+declare const GridlerSearch: import("svelte").Component<Props, {
+    focus: () => void;
+}, "">;
 type GridlerSearch = ReturnType<typeof GridlerSearch>;
 export default GridlerSearch;

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

@@ -11,6 +11,12 @@
   }
 
   const { show, value, onToggle, onValueChange, onClose }: Props = $props();
+
+  let search: GridlerSearch | undefined = $state();
+
+  $effect(() => {
+    if (show) search?.focus();
+  });
 </script>
 
 <button
@@ -25,6 +31,7 @@
 
 {#if show}
   <GridlerSearch
+    bind:this={search}
     {value}
     {onValueChange}
     {onClose}

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

@@ -1,4 +1,4 @@
-import type { GridColumn, GridCommonProps, GridColumnSortOrder, GridColumnFilters } from '../Types/generic_grid';
+import type { GridColumn, GridCommonProps, GridColumnSortOrder, GridColumnFilters, GridContextMenuItem } from '../Types/generic_grid';
 import type { Options } from '@warkypublic/resolvespec-js';
 export type { GridColumnSortOrder, GridColumnFilters };
 export type Item = [col: number, row: number];
@@ -60,8 +60,6 @@ export interface GridlerColumn extends GridColumn<Record<string, unknown>> {
     width: number;
     /** Per-column theme overrides applied during canvas rendering. */
     themeOverride?: Partial<GridlerTheme>;
-    /** Show a context-menu trigger button on this column's header. */
-    hasMenu?: boolean;
 }
 export interface GridlerCellFormatOptions {
     /** Currency code for 'currency' cells (default: 'ZAR'). */
@@ -155,8 +153,8 @@ export interface GridlerProps extends GridCommonProps<Record<string, unknown>> {
     theme?: Partial<GridlerTheme>;
     /** Controlled selection state. */
     selection?: Selection;
-    /** Called when the internal selection changes. */
-    onSelectionChange?: (selection: Selection) => void;
+    /** Called when the internal selection changes. Row data for all selected rows is provided where available. */
+    onSelectionChange?: (selection: Selection, rowData?: Record<string, unknown>[]) => void;
     /** Called when the visible row/column range changes (e.g. on scroll). */
     onVisibleRangeChange?: (range: VisibleRange) => void;
     /** When true, all cells are read-only. Also settable via settings.readonly. */
@@ -166,14 +164,6 @@ export interface GridlerProps extends GridCommonProps<Record<string, unknown>> {
     /** Show the built-in search bar. Also settable via settings.showSearch. */
     showSearch?: boolean;
 }
-export interface GridlerContextMenuItem {
-    id: string;
-    label: string;
-    disabled?: boolean;
-    icon?: string;
-    /** Use 'separator' to render a divider line. */
-    kind?: 'item' | 'separator';
-    onselect?: (rowData?: Record<string, unknown>) => void;
-}
+export type GridlerContextMenuItem = GridContextMenuItem<Record<string, unknown>>;
 export declare const DEFAULT_THEME: GridlerTheme;
 export declare const DEFAULT_THEME_DARK: GridlerTheme;

package/dist/components/Gridler/utils/cellContent.js

@@ -1,8 +1,9 @@
+import { getNestedValue } from "@warkypublic/artemis-kit/object";
 export function rowToCell(row, key) {
     if (row === undefined) {
         return { kind: "text", data: null, displayData: "", allowOverlay: false, allowEditing: false };
     }
-    const raw = key ? row[key] : undefined;
+    const raw = key ? getNestedValue(key, row) : undefined;
     const display = raw == null ? "" : String(raw);
     if (typeof raw === "number") {
         return { kind: "number", data: raw, displayData: display, allowOverlay: true, allowEditing: true };

package/dist/components/Gridler/utils/filters.js

@@ -1,3 +1,4 @@
+import { getNestedValue } from "@warkypublic/artemis-kit/object";
 export function gridColumnFiltersToFilterOptions(f) {
     return Object.entries(f).map(([id, filter]) => ({
         column: filter.dataKey ?? id,
@@ -15,8 +16,7 @@ export function applyLocalFilter(data, filters, columns) {
         for (const [colId, filter] of entries) {
             const colDef = columns.find((c) => c.id === colId);
             const key = colDef?.dataKey ?? colId;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const rawVal = row[key];
+            const rawVal = getNestedValue(key, row);
             const cellStr = rawVal == null ? "" : String(rawVal).toLowerCase();
             const filterVal = filter.value?.toLowerCase() ?? "";
             const op = filter.op ?? "contains";

package/dist/components/Gridler/utils/sort.js

@@ -1,3 +1,4 @@
+import { getNestedValue } from "@warkypublic/artemis-kit/object";
 export function compareValues(a, b) {
     if (a == null && b == null)
         return 0;
@@ -27,7 +28,7 @@ export function applyLocalSort(data, sortOptions, columns) {
         for (const { column, direction } of sortOptions) {
             const colDef = columns.find((c) => c.id === column);
             const key = colDef?.dataKey ?? column;
-            const cmp = compareValues(a[key], b[key]);
+            const cmp = compareValues(getNestedValue(key, a), getNestedValue(key, b));
             if (cmp !== 0)
                 return direction === "asc" ? cmp : -cmp;
         }

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

@@ -25,6 +25,8 @@ export interface GridColumn<RowDataType = unknown, CellType = unknown> {
     disableSearch?: boolean | ((item: RowDataType) => boolean);
     span?: [startRow: number, endRow: number];
     renderCell?: (item: RowDataType) => CellType;
+    /** Show a context-menu trigger button on this column's header. */
+    hasMenu?: boolean;
 }
 export interface GridColumnSortOrder {
     [id: string]: "asc" | "desc" | "none";
@@ -44,34 +46,74 @@ export interface GridEventCoords {
     code?: string;
 }
 export type GridEventDetail = Record<string, unknown>;
+/** Generic context-menu item. Implementations (e.g. GridlerContextMenuItem) extend this. */
+export interface GridContextMenuItem<RowDataType = unknown> {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    icon?: string;
+    /** Use 'separator' to render a divider line. */
+    kind?: 'item' | 'separator';
+    onselect?: (rowData?: RowDataType) => void;
+}
 export interface GridCommonProps<RowDataType = unknown, CellType = unknown> {
     columns: Array<GridColumn<RowDataType, CellType>>;
     width?: string | number;
     height?: string | number;
     rowHeight?: number;
     headerHeight?: number;
-    onCellEvent?: (type: GridCellEventType, item: RowDataType, column: GridColumn<RowDataType, CellType>, coords?: GridEventCoords, // For keyboard/mouse events, code represents the key code of the pressed key
-    detail?: GridEventDetail) => void;
-    onGridEvent?: (type: GridEventType, item?: RowDataType, column?: GridColumn<RowDataType, CellType>, coords?: GridEventCoords, // For keyboard/mouse events, code represents the key code of the pressed key
-    detail?: GridEventDetail) => void;
+    /** Number of columns pinned to the left. */
+    fixedColumns?: number;
+    /** When true, the grid manages column reordering internally on drag. */
+    manageColumns?: boolean;
+    /** Called when the internal column order changes (only fires when manageColumns is true). */
+    onColumnsChange?: (columns: GridColumn<RowDataType, CellType>[]) => void;
+    onCellEvent?: (type: GridCellEventType, item: RowDataType, column: GridColumn<RowDataType, CellType>, coords?: GridEventCoords, detail?: GridEventDetail) => void;
+    onGridEvent?: (type: GridEventType, item?: RowDataType, column?: GridColumn<RowDataType, CellType>, coords?: GridEventCoords, detail?: GridEventDetail) => void;
     onMenuClick?: (item?: RowDataType, column?: GridColumn<RowDataType, CellType>, coords?: GridEventCoords) => Promise<void>;
+    /** Called when a body row is clicked. */
+    onRowClick?: (row: number, rowData?: RowDataType) => void;
+    /** Called when a body row is double-clicked. */
+    onRowDblClick?: (row: number, rowData?: RowDataType) => void;
+    /** Called when a body row receives a context-menu event. */
+    onRowContextMenu?: (row: number, rowData?: RowDataType, x?: number, y?: number) => void;
+    /** Called when a cell is double-clicked. */
+    onCellDblClick?: (row: number, column: GridColumn<RowDataType, CellType>, rowData?: RowDataType) => void;
     onColumnMoved?: (startIndex: number, endIndex: number) => void;
     onSortOrderChange?: (sortOrder: GridColumnSortOrder) => void;
     sortOrder?: GridColumnSortOrder;
     onFilterChange?: (filters: GridColumnFilters) => void;
     filters?: GridColumnFilters;
-    onSearchValueChange?: (value: string) => void;
     searchValue?: string;
+    /** Uncontrolled initial search value (only used when searchValue is undefined). */
+    defaultSearchValue?: string;
+    onSearchValueChange?: (value: string) => void;
+    /**
+     * When true, the search input value is translated into server-side filters
+     * instead of only being used for client-side highlighting.
+     */
+    serverSideSearch?: boolean;
+    /** Columns searched when serverSideSearch is true. Defaults to all columns. */
+    searchColumns?: string[];
     selectedItems?: RowDataType[];
     onSelectedItemsChange?: (items: RowDataType[]) => void;
+    /** Extra items appended to the built-in context menu. */
+    menuItems?: GridContextMenuItem<RowDataType>[];
+    /** Called when any context menu item is selected (built-in or custom). */
+    onMenuItemSelect?: (item: GridContextMenuItem<RowDataType>, rowData?: RowDataType) => void;
     dataSource?: "local" | "resolvespec" | "headerspec" | "websockspec" | "custom";
     dataSourceOptions?: {
         url?: string;
         authToken?: string;
         schema?: string;
         entity?: string;
+        /**
+         * Row field whose value is used as the cursor for subsequent page requests.
+         * Defaults to 'id'. Can also be set via the top-level uniqueID shorthand.
+         */
         uniqueID?: string;
         headers?: Record<string, string>;
+        /** Fields to fetch in addition to column fields (for filters, sort, relations). */
         hotfields?: string[];
         /**
          * Default ResolveSpec options sent with every request. Grid-controlled sort, filters, limit,
@@ -93,6 +135,32 @@ export interface GridCommonProps<RowDataType = unknown, CellType = unknown> {
     };
     data?: RowDataType[] | (() => Promise<RowDataType[]>);
     onDataChange?: (data: RowDataType[]) => Promise<void>;
+    /** Rows per cursor-forward page. Defaults to 200. */
+    pageSize?: number;
+    /**
+     * Shorthand for dataSourceOptions.uniqueID.
+     * Row field whose value is passed as cursor_forward on subsequent requests.
+     */
+    uniqueID?: string;
+    /** Called when a server fetch fails. */
+    onLoadError?: (error: string) => void;
+    /**
+     * Bindable. Reflects the server-reported total row count.
+     * Updated after every successful page fetch; 0 until the first response.
+     */
+    total?: number;
+    /**
+     * Bindable. true while any server fetch is in flight.
+     */
+    loading?: boolean;
+    /** When true, all cells are read-only. Also settable via settings.readonly. */
+    readonly?: boolean;
+    /** Allow users to drag column edges to resize. Also settable via settings.resizableColumns. */
+    resizableColumns?: boolean;
+    /** Show the built-in search bar. Also settable via settings.showSearch. */
+    showSearch?: boolean;
+    /** Row-marker style shown in the leading column. Also settable via settings.rowMarkerType. */
+    rowMarkers?: "checkbox" | "number" | "none";
     settings?: {
         hideHeader?: boolean;
         showRowMarkers?: boolean;

package/llm/IMPLEMENTATION_PLAN.md

@@ -41,6 +41,7 @@ This file now tracks the implemented state of the project rather than the origin
 ### Data and explorer components
 - `Gridler`
 - `GridlerFull`
+  - `onSelectionChange(selection, rowData?)` — second arg carries resolved row data for all selected rows (cell, row, range types)
 - `SvarkGrid`
 - `VTree`
 - shared generic grid types and supporting utilities

package/llm/gridler-events.md

@@ -39,7 +39,7 @@ onGridEvent?: (
 | `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 | — | — | — | — |
+| `selection_changed` | Cell, row, range, or column selection changes | — | — | — | — | (use `onSelectionChange` for the selection object + row data) |
 | `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 |
@@ -47,6 +47,55 @@ onGridEvent?: (
 
 ---
 
+## `onSelectionChange`
+
+Fired on every selection change — mouse clicks, arrow-key navigation, Ctrl+A, row-marker toggles.
+
+```ts
+onSelectionChange?: (
+  selection: Selection,
+  rowData?: Record<string, unknown>[],  // resolved row data for all selected rows
+) => void
+```
+
+### `Selection` type
+
+```ts
+type Selection =
+  | { type: "none" }
+  | { type: "cell";   item: [col, row] }
+  | { type: "range";  start: [col, row]; end: [col, row] }
+  | { type: "row";    rows: number[] }
+  | { type: "column"; columns: number[] }
+```
+
+### `rowData` population
+
+| Selection type | `rowData` |
+|---|---|
+| `cell` | single-element array with the row's data |
+| `row` | array of data for each selected row |
+| `range` | array of data for every row from `start[1]` to `end[1]` |
+| `column` / `none` | `undefined` |
+
+`rowData` is `undefined` when no row data can be resolved (column/none selections, or when `getRowData`/`data` is not provided).
+
+### Usage
+
+```svelte
+<GridlerFull
+  {columns}
+  {data}
+  onSelectionChange={(sel, rowData) => {
+    if (sel.type === 'cell') {
+      console.log('Selected row:', rowData?.[0]);
+    }
+  }}
+/>
+```
+
+---
+
 ## `onCellEvent`
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warkypublic/svelix",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "description": "Svelte 5 component library with Skeleton UI and Tailwind CSS",
   "license": "Apache-2.0",
   "exports": {