@warkypublic/svelix 0.1.41 → 0.1.43

package/dist/components/ContentEditor/subcomponents/TextEditor.svelte

@@ -147,33 +147,18 @@
 
 const contentPaddingClass = $derived(hideHeader ? 'p-0' : 'p-4');
 
-type TipexControlEditor = {
-  isActive: (name: string, attrs?: Record<string, unknown>) => boolean;
-  chain: () => {
-    focus: () => {
-      toggleHeading: (opts: { level: number }) => { run: () => void };
-      setParagraph: () => { run: () => void };
-      toggleBold: () => { run: () => void };
-      toggleItalic: () => { run: () => void };
-      toggleUnderline: () => { run: () => void };
-      toggleBulletList: () => { run: () => void };
-      toggleOrderedList: () => { run: () => void };
-      toggleTaskList: () => { run: () => void };
-      toggleBlockquote: () => { run: () => void };
-      toggleCodeBlock: () => { run: () => void };
-    };
-  };
-};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function echain(editor: TipexEditor): any { return echain(editor) ?? {}; }
 </script>
 
-{#snippet controlComponent(editor: TipexControlEditor)}
+{#snippet controlComponent(editor: TipexEditor)}
   <div class="tipex-controller">
     <div class="tipex-basic-controller-wrapper">
       <button
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('heading', { level: 1 })}
-        onclick={() => editor?.chain().focus().toggleHeading({ level: 1 }).run()}
+        onclick={() => echain(editor).toggleHeading({ level: 1 }).run()}
         aria-label="Heading 1"
         title="Heading 1"
       >
@@ -183,7 +168,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('heading', { level: 2 })}
-        onclick={() => editor?.chain().focus().toggleHeading({ level: 2 }).run()}
+        onclick={() => echain(editor).toggleHeading({ level: 2 }).run()}
         aria-label="Heading 2"
         title="Heading 2"
       >
@@ -193,7 +178,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('paragraph')}
-        onclick={() => editor?.chain().focus().setParagraph().run()}
+        onclick={() => echain(editor).setParagraph().run()}
         aria-label="Paragraph"
         title="Paragraph"
       >
@@ -206,7 +191,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('bold')}
-        onclick={() => editor?.chain().focus().toggleBold().run()}
+        onclick={() => echain(editor).toggleBold().run()}
         aria-label="Bold"
         title="Bold"
       >
@@ -216,7 +201,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('italic')}
-        onclick={() => editor?.chain().focus().toggleItalic().run()}
+        onclick={() => echain(editor).toggleItalic().run()}
         aria-label="Italic"
         title="Italic"
       >
@@ -226,7 +211,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('underline')}
-        onclick={() => editor?.chain().focus().toggleUnderline().run()}
+        onclick={() => echain(editor).toggleUnderline().run()}
         aria-label="Underline"
         title="Underline"
       >
@@ -239,7 +224,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('bulletList')}
-        onclick={() => editor?.chain().focus().toggleBulletList().run()}
+        onclick={() => echain(editor).toggleBulletList().run()}
         aria-label="Bullet list"
         title="Bullet list"
       >
@@ -251,7 +236,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('orderedList')}
-        onclick={() => editor?.chain().focus().toggleOrderedList().run()}
+        onclick={() => echain(editor).toggleOrderedList().run()}
         aria-label="Ordered list"
         title="Ordered list"
       >
@@ -263,7 +248,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('taskList')}
-        onclick={() => editor?.chain().focus().toggleTaskList().run()}
+        onclick={() => echain(editor).toggleTaskList().run()}
         aria-label="Task list"
         title="Task list"
       >
@@ -279,7 +264,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('blockquote')}
-        onclick={() => editor?.chain().focus().toggleBlockquote().run()}
+        onclick={() => echain(editor).toggleBlockquote().run()}
         aria-label="Blockquote"
         title="Blockquote"
       >
@@ -291,7 +276,7 @@ type TipexControlEditor = {
         type="button"
         class="tipex-edit-button tipex-button-extra tipex-button-rigid"
         class:active={editor?.isActive('codeBlock')}
-        onclick={() => editor?.chain().focus().toggleCodeBlock().run()}
+        onclick={() => echain(editor).toggleCodeBlock().run()}
         aria-label="Code block"
         title="Code block"
       >

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

@@ -28,7 +28,7 @@
       column?: GridlerColumn;
     }) => void;
     onRowClick?: (row: number) => void;
-    onRowContextMenu?: (row: number) => void;
+    onRowContextMenu?: (row: number, x: number, y: number) => void;
     /** Resolve raw row data by row index for populating onCellEvent. */
     getRowData?: (row: number) => Record<string, unknown> | undefined;
     children?: Snippet;
@@ -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) => {
@@ -472,8 +495,8 @@
     onCellEvent?.("contextmenu", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" }, { x, y });
     onGridEvent?.("contextmenu", getRowData?.(item[1]) ?? {}, columns[item[0]] ?? { id: "", title: "" }, { x, y });
   }}
-  onRowContextMenu={(row) => {
-    onRowContextMenu?.(row);
+  onRowContextMenu={(row, x, y) => {
+    onRowContextMenu?.(row, x, y);
   }}
   onColumnResized={(col, newWidth) => {
     columns[col].width = newWidth;

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

@@ -14,7 +14,7 @@ export interface Props extends Partial<GridlerProps> {
         column?: GridlerColumn;
     }) => void;
     onRowClick?: (row: number) => void;
-    onRowContextMenu?: (row: number) => void;
+    onRowContextMenu?: (row: number, x: number, y: number) => void;
     /** Resolve raw row data by row index for populating onCellEvent. */
     getRowData?: (row: number) => Record<string, unknown> | undefined;
     children?: Snippet;

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

@@ -58,7 +58,7 @@
     onSelectionChange?: (sel: Selection) => void;
     onCellDblClick?: (item: Item, cell: GridlerCell) => void;
     onRowClick?: (row: number) => void;
-    onRowContextMenu?: (row: number) => void;
+    onRowContextMenu?: (row: number, x: number, y: number) => void;
     onColumnMoved?: (from: number, to: number) => void;
     onCellEdited?: (item: Item, cell: GridlerCell) => void;
     onDelete?: (sel: Selection) => void;
@@ -480,7 +480,7 @@
     const row = getRowFromOffsetY(e.offsetY);
     if (row !== null) {
       e.preventDefault();
-      onRowContextMenu?.(row);
+      onRowContextMenu?.(row, e.clientX, e.clientY);
     }
 
     if (e.offsetX < rowMarkerWidth) return;

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

@@ -27,7 +27,7 @@ interface Props {
     onSelectionChange?: (sel: Selection) => void;
     onCellDblClick?: (item: Item, cell: GridlerCell) => void;
     onRowClick?: (row: number) => void;
-    onRowContextMenu?: (row: number) => void;
+    onRowContextMenu?: (row: number, x: number, y: number) => void;
     onColumnMoved?: (from: number, to: number) => void;
     onCellEdited?: (item: Item, cell: GridlerCell) => void;
     onDelete?: (sel: Selection) => void;

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

@@ -88,10 +88,12 @@
       row: number,
       rowData: Record<string, unknown> | undefined,
     ) => void;
-    /** Called on row context-menu with the row index and resolved row data. */
+    /** Called on row context-menu with the row index, resolved row data, and click coordinates. */
     onRowContextMenu?: (
       row: number,
       rowData: Record<string, unknown> | undefined,
+      x: number,
+      y: number,
     ) => void;
 
     // ── Server-side fetching ──────────────────────────────────────────────────
@@ -120,13 +122,25 @@
     /** 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.
+     * Read-only from the parent — do not write this value.
+     */
+    total?: number;
+    /**
+     * Bindable. `true` while any server fetch is in flight (initial load or next-page).
+     * Read-only from the parent — do not write this value.
+     */
+    loading?: boolean;
+
     /**
      * Extra items appended to the built-in context menu (Refresh, Clear Search, Clear Filters, Clear Sort).
      * Pass a separator item `{ id: 'sep', kind: 'separator', label: '' }` to group your items.
      */
     menuItems?: GridlerContextMenuItem[];
     /** Called when any context menu item is selected (built-in or custom). */
-    onMenuItemSelect?: (item: GridlerContextMenuItem) => void;
+    onMenuItemSelect?: (item: GridlerContextMenuItem, rowData?: Record<string, unknown>) => void;
 
     children?: Snippet;
   }
@@ -150,6 +164,8 @@
     serverSideSearch = false,
     searchColumns,
     onLoadError,
+    total = $bindable(0),
+    loading = $bindable(false),
     // GridCommonProps filters/sort (generic types)
     filters,
     onFilterChange,
@@ -285,6 +301,7 @@
   // ── Context menu ───────────────────────────────────────────────────────────
 
   let refreshTrigger = $state(0);
+  let contextMenuRowData = $state<Record<string, unknown> | undefined>(undefined);
   let menu = $state<{
     show: (
       id: string,
@@ -347,8 +364,8 @@
             label: item.label,
             icon: item.icon,
             onClick: () => {
-              item.onselect?.();
-              onMenuItemSelect?.(item);
+              item.onselect?.(contextMenuRowData);
+              onMenuItemSelect?.(item, contextMenuRowData);
             },
           });
         }
@@ -523,6 +540,9 @@
   let serverFetchVersion = 0;
   let serverLoading = $state(false);
   let serverAllLoaded = $state(false);
+
+  $effect(() => { total = serverTotal; });
+  $effect(() => { loading = serverLoading; });
   let serverError = $state<string | null>(null);
 
   type Adapter = GridlerResolveSpecAdapter | GridlerRestHeaderSpecAdapter;
@@ -704,8 +724,10 @@
     onRowClick?.(row, resolveRowData(row));
   }
 
-  function handleRowContextMenu(row: number) {
-    onRowContextMenu?.(row, resolveRowData(row));
+  function handleRowContextMenu(row: number, x: number, y: number) {
+    contextMenuRowData = resolveRowData(row);
+    menu?.show("gridler-menu", { x, y, items: buildMenuItems() });
+    onRowContextMenu?.(row, contextMenuRowData, x, y);
   }
 
   // ── Selection → selectedItems bridge ──────────────────────────────────────
@@ -736,7 +758,7 @@
     }
     internalSelectedItems = items;
     if (items.length > 0) onSelectedItemsChange?.(items);
-    onSelectionChange?.(sel);
+    onSelectionChange?.(sel, items.length > 0 ? items : undefined);
   }
 
   // ── Settings change event ─────────────────────────────────────────────────
@@ -795,6 +817,7 @@
     item?: Record<string, unknown>;
     column?: GridlerColumn;
   }) {
+    contextMenuRowData = undefined;
     if (onMenuClick) {
       await onMenuClick(
         d?.item,
@@ -806,6 +829,16 @@
     if (!d) return;
     menu?.show("gridler-menu", { x: d.x, y: d.y, items: buildMenuItems() });
   }
+
+  // ── Public API ────────────────────────────────────────────────────────────
+
+  export function getSelectedRows(): Record<string, unknown>[] {
+    return internalSelectedItems;
+  }
+
+  export function getLoadedData(): Record<string, unknown>[] {
+    return isServerMode ? serverData : filteredDataState;
+  }
 </script>
 
 <BetterMenu bind:this={menu}>

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

@@ -30,8 +30,8 @@ export interface Props extends Omit<Partial<GridlerProps>, "columns" | "rows" |
     onRowDblClick?: (row: number, rowData: Record<string, unknown> | undefined) => void;
     /** Called on row click with the row index and resolved row data. */
     onRowClick?: (row: number, rowData: Record<string, unknown> | undefined) => void;
-    /** Called on row context-menu with the row index and resolved row data. */
-    onRowContextMenu?: (row: number, rowData: Record<string, unknown> | undefined) => void;
+    /** Called on row context-menu with the row index, resolved row data, and click coordinates. */
+    onRowContextMenu?: (row: number, rowData: Record<string, unknown> | undefined, x: number, y: number) => void;
     /** Rows per cursor-forward page. Defaults to 200. */
     pageSize?: number;
     /**
@@ -52,15 +52,29 @@ export interface Props extends Omit<Partial<GridlerProps>, "columns" | "rows" |
     searchColumns?: 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.
+     * Read-only from the parent — do not write this value.
+     */
+    total?: number;
+    /**
+     * Bindable. `true` while any server fetch is in flight (initial load or next-page).
+     * Read-only from the parent — do not write this value.
+     */
+    loading?: boolean;
     /**
      * Extra items appended to the built-in context menu (Refresh, Clear Search, Clear Filters, Clear Sort).
      * Pass a separator item `{ id: 'sep', kind: 'separator', label: '' }` to group your items.
      */
     menuItems?: GridlerContextMenuItem[];
     /** Called when any context menu item is selected (built-in or custom). */
-    onMenuItemSelect?: (item: GridlerContextMenuItem) => void;
+    onMenuItemSelect?: (item: GridlerContextMenuItem, rowData?: Record<string, unknown>) => void;
     children?: Snippet;
 }
-declare const GridlerFull: import("svelte").Component<Props, {}, "">;
+declare const GridlerFull: import("svelte").Component<Props, {
+    getSelectedRows: () => Record<string, unknown>[];
+    getLoadedData: () => Record<string, unknown>[];
+}, "loading" | "total">;
 type GridlerFull = ReturnType<typeof GridlerFull>;
 export default GridlerFull;

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

@@ -155,8 +155,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. */
@@ -173,7 +173,7 @@ export interface GridlerContextMenuItem {
     icon?: string;
     /** Use 'separator' to render a divider line. */
     kind?: 'item' | 'separator';
-    onselect?: () => void;
+    onselect?: (rowData?: Record<string, unknown>) => void;
 }
 export declare const DEFAULT_THEME: GridlerTheme;
 export declare const DEFAULT_THEME_DARK: GridlerTheme;

package/dist/components/SvarkGrid/internal/SvarkGridView.svelte

@@ -376,12 +376,10 @@
 			contextMenuY = ev.clientY;
 
 			const ctxRowId = (resolved?.id ?? selectedIds[0] ?? null) as string | number | null;
-			const ctxRow =
-				resolved?.row ??
-				(ctxRowId != null
+			const ctxRow: Record<string, unknown> | null =
+				ctxRowId != null
 					? data.find((item) => String(item?.[uniqueID]) === String(ctxRowId)) ?? null
-					: null) ??
-				null;
+					: null;
 
 			contextMenuRowId = ctxRowId;
 			contextMenuRow = ctxRow;

package/llm/COMPONENT_GUIDE.md

@@ -570,6 +570,78 @@ These are `Partial<Options>` from `@warkypublic/resolvespec-js`. Grid-controlled
 | `where`              | Raw SQL WHERE fragment for the relation.             |
 | `updatable`          | Marks the preloaded relation as updatable.           |
 
+#### Bindable state props
+
+| Prop      | Type      | Description                                                                 |
+|-----------|-----------|-----------------------------------------------------------------------------|
+| `total`   | `number`  | Server-reported total row count. Updated after every successful page fetch. |
+| `loading` | `boolean` | `true` while any fetch is in flight (initial load or next-page append).     |
+
+Both are read-only from the parent's perspective — bind them to a variable, do not pass a value in:
+
+```svelte
+<script lang="ts">
+	let total = $state(0);
+	let loading = $state(false);
+</script>
+
+<GridlerFull bind:total bind:loading {columns} dataSource="resolvespec" {dataSourceOptions} />
+
+{#if loading}<span>Loading…</span>{/if}
+<span>{total} rows</span>
+```
+
+#### Row/cell callbacks (GridlerFull enriches with row data)
+
+| Callback | Signature | Notes |
+|---|---|---|
+| `onCellDblClick` | `(item: Item, cell: GridlerCell, rowData?)` | Double-click on a cell. |
+| `onRowDblClick` | `(row: number, rowData?)` | Double-click on a row (fires alongside `onCellDblClick`). |
+| `onRowClick` | `(row: number, rowData?)` | Single click on a body row. |
+| `onRowContextMenu` | `(row: number, rowData?, x: number, y: number)` | Right-click on a body row. `x`/`y` are viewport pixel coordinates. |
+| `onDataChange` | `(data: Record<string, unknown>[]) => Promise<void>` | Fires after an inline cell edit mutates local `dataState`. Server mode: not called. |
+| `onColumnsChange` | `(columns: GridlerColumn[]) => void` | Fires when `manageColumns` reorders columns. |
+| `onSearchValueChange` | `(value: string) => void` | Fires on every search input change. |
+| `onLoadError` | `(error: string) => void` | Fires on any adapter fetch failure. |
+| `onMenuItemSelect` | `(item: GridlerContextMenuItem, rowData?) => void` | Fires for both built-in and custom context menu items. |
+
+`rowData` is `Record<string, unknown> | undefined` — it maps to the loaded row object for the clicked row index, or `undefined` if the row has not been loaded yet.
+
+#### Context menu customisation
+
+```svelte
+<GridlerFull
+  {columns}
+  menuItems={[
+    { id: 'edit', label: 'Edit', icon: 'pencil' },
+    { id: 'sep', kind: 'separator', label: '' },
+    { id: 'delete', label: 'Delete', icon: 'trash', onselect: (row) => handleDelete(row) },
+  ]}
+  onMenuItemSelect={(item, rowData) => console.log(item.id, rowData)}
+/>
+```
+
+Built-in items (Refresh, Clear Search, Clear Filters, Clear Sort) appear first; custom `menuItems` are appended after a divider.
+
+#### Public methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `getSelectedRows()` | `Record<string, unknown>[]` | Currently selected row objects. |
+| `getLoadedData()` | `Record<string, unknown>[]` | All rows in the current data set (filtered local data or full server page buffer). |
+
+```svelte
+<script lang="ts">
+  import { GridlerFull } from '@warkypublic/svelix';
+
+  let grid: ReturnType<typeof GridlerFull>;
+</script>
+
+<GridlerFull bind:this={grid} {columns} {dataSourceOptions} />
+
+<button onclick={() => console.log(grid.getSelectedRows())}>Log selection</button>
+```
+
 Key behaviors:
 - `extraOptions` is stored on the adapter at construction time; changing `dataSourceOptions` recreates the adapter and triggers a full refetch.
 - Call-time `extraOptions` passed directly to `readPage` override the config-level defaults; specific params (sort, filters, limit, cursor, columns) override both.

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.41",
+  "version": "0.1.43",
   "description": "Svelte 5 component library with Skeleton UI and Tailwind CSS",
   "license": "Apache-2.0",
   "exports": {