@warkypublic/svelix 0.1.40 → 0.1.42

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/adapters/GridlerResolveSpecAdapter.d.ts

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

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

@@ -4,18 +4,21 @@ export class GridlerResolveSpecAdapter {
     client;
     schema;
     entity;
+    configExtraOptions;
     uniqueID;
     constructor(config) {
         this.client = new ResolveSpecClient({ baseUrl: config.url, token: config.token });
         this.schema = config.schema;
         this.entity = config.entity;
         this.uniqueID = config.uniqueID ?? 'id';
+        this.configExtraOptions = config.extraOptions ?? {};
     }
     async readPage(limit, cursorForward, sort, filters, fields, extraOptions) {
+        const merged = { ...this.configExtraOptions, ...extraOptions };
         const options = {
-            ...extraOptions,
-            sort: sort ?? extraOptions?.sort ?? [],
-            filters: filters ?? extraOptions?.filters ?? [],
+            ...merged,
+            sort: sort ?? merged.sort ?? [],
+            filters: filters ?? merged.filters ?? [],
             limit,
             ...(cursorForward != null ? { cursor_forward: cursorForward } : {}),
             ...(fields?.length ? { columns: fields } : {}),

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

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

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

@@ -4,18 +4,21 @@ export class GridlerRestHeaderSpecAdapter {
     client;
     schema;
     entity;
+    configExtraOptions;
     uniqueID;
     constructor(config) {
         this.client = new HeaderSpecClient({ baseUrl: config.url, token: config.token });
         this.schema = config.schema;
         this.entity = config.entity;
         this.uniqueID = config.uniqueID ?? 'id';
+        this.configExtraOptions = config.extraOptions ?? {};
     }
     async readPage(limit, cursorForward, sort, filters, fields, extraOptions) {
+        const merged = { ...this.configExtraOptions, ...extraOptions };
         const options = {
-            ...extraOptions,
-            sort: sort ?? extraOptions?.sort ?? [],
-            filters: filters ?? extraOptions?.filters ?? [],
+            ...merged,
+            sort: sort ?? merged.sort ?? [],
+            filters: filters ?? merged.filters ?? [],
             limit,
             ...(cursorForward != null ? { cursor_forward: cursorForward } : {}),
             ...(fields?.length ? { columns: fields } : {}),

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;
@@ -472,8 +472,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;
@@ -535,6 +555,7 @@
       schema: resolvedSchema,
       entity: resolvedEntity,
       uniqueID: resolvedUniqueID,
+      extraOptions: dataSourceOptions?.extraOptions,
     };
     return dataSource === "headerspec"
       ? new GridlerRestHeaderSpecAdapter(config)
@@ -703,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 ──────────────────────────────────────
@@ -794,6 +817,7 @@
     item?: Record<string, unknown>;
     column?: GridlerColumn;
   }) {
+    contextMenuRowData = undefined;
     if (onMenuClick) {
       await onMenuClick(
         d?.item,
@@ -805,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

@@ -1,4 +1,5 @@
 import type { GridColumn, GridCommonProps, GridColumnSortOrder, GridColumnFilters } from '../Types/generic_grid';
+import type { Options } from '@warkypublic/resolvespec-js';
 export type { GridColumnSortOrder, GridColumnFilters };
 export type Item = [col: number, row: number];
 export interface GridlerAdapterConfig {
@@ -8,6 +9,23 @@ export interface GridlerAdapterConfig {
     entity: string;
     /** Row field whose value is passed as cursor_forward on subsequent requests. Defaults to 'id'. */
     uniqueID?: string;
+    /**
+     * Default ResolveSpec options applied to every request. Grid-controlled sort, filters, limit,
+     * cursor, and columns always take precedence over values set here.
+     *
+     * Key fields:
+     * - `preload`          — eager-load relations. Each entry specifies `relation`, optional `columns`,
+     *                        `filters`, `sort`, `limit`, `recursive`, `sql_joins`, etc.
+     * - `omit_columns`     — columns to exclude from the response.
+     * - `computedColumns`  — server-side computed expressions: `{ name, expression }`.
+     * - `customOperators`  — raw SQL WHERE fragments (AND-combined): `{ name, sql }`.
+     * - `parameters`       — named query parameters passed to the server: `{ name, value, sequence? }`.
+     * - `filters`          — default server-side filters applied before any grid filters.
+     * - `sort`             — default sort order, overridden when the user sorts a column.
+     * - `fetch_row_number` — column name whose row number is returned in metadata.
+     * - `offset`           — static row offset (cursor pagination is used by the adapter; avoid mixing).
+     */
+    extraOptions?: Partial<Options>;
 }
 export interface GridlerPageResult {
     data: Record<string, unknown>[];
@@ -155,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/dist/components/Types/generic_grid.d.ts

@@ -1,3 +1,4 @@
+import type { Options as ResolveSpecOptions } from '@warkypublic/resolvespec-js';
 export type GridColumnFormat = "text" | "number" | "currency" | "percentage" | "date" | "datetime" | "markdown" | "image" | "uri" | "bubble" | "drilldown";
 /**
  * GridEventType represents the various events that can occur on the grid level, such as clicking, hovering, loading, scrolling, resizing, and changes to sorting, filtering, searching, selection, column arrangement, data, and settings. These events can be used to trigger callbacks for handling user interactions and updates to the grid.
@@ -72,6 +73,23 @@ export interface GridCommonProps<RowDataType = unknown, CellType = unknown> {
         uniqueID?: string;
         headers?: Record<string, string>;
         hotfields?: string[];
+        /**
+         * Default ResolveSpec options sent with every request. Grid-controlled sort, filters, limit,
+         * cursor, and columns always take precedence over values set here.
+         *
+         * Key fields:
+         * - `preload`          — eager-load relations. Each entry specifies `relation`, optional `columns`,
+         *                        `filters`, `sort`, `limit`, `recursive`, `sql_joins`, etc.
+         * - `omit_columns`     — columns to exclude from the response.
+         * - `computedColumns`  — server-side computed expressions: `{ name, expression }`.
+         * - `customOperators`  — raw SQL WHERE fragments (AND-combined): `{ name, sql }`.
+         * - `parameters`       — named query parameters passed to the server: `{ name, value, sequence? }`.
+         * - `filters`          — default server-side filters applied before any grid filters.
+         * - `sort`             — default sort order, overridden when the user sorts a column.
+         * - `fetch_row_number` — column name whose row number is returned in metadata.
+         * - `offset`           — static row offset (cursor pagination is used by the adapter; avoid mixing).
+         */
+        extraOptions?: Partial<ResolveSpecOptions>;
     };
     data?: RowDataType[] | (() => Promise<RowDataType[]>);
     onDataChange?: (data: RowDataType[]) => Promise<void>;

package/llm/COMPONENT_GUIDE.md

@@ -478,6 +478,176 @@ Story behavior worth preserving:
 - search highlighting and fixed columns are first-class usage patterns
 - theme overrides are an expected integration point, not a niche feature
 
+### GridlerFull: server-driven Gridler with adapters
+
+`GridlerFull` wraps `Gridler` and handles paging, sorting, filtering, and search against a
+ResolveSpec or HeaderSpec API. Configure via `dataSource` + `dataSourceOptions`.
+
+```svelte
+<script lang="ts">
+	import { GridlerFull } from '@warkypublic/svelix';
+	import type { GridlerColumn } from '@warkypublic/svelix';
+
+	const columns: GridlerColumn[] = [
+		{ id: 'id',    title: 'ID',    width: 60  },
+		{ id: 'name',  title: 'Name',  width: 180 },
+		{ id: 'email', title: 'Email', width: 220 },
+	];
+</script>
+
+<GridlerFull
+	{columns}
+	dataSource="resolvespec"
+	dataSourceOptions={{
+		url: 'https://api.example.com',
+		authToken: 'Bearer …',
+		schema: 'public',
+		entity: 'users',
+		uniqueID: 'id',
+		hotfields: ['role'],
+		extraOptions: {
+			preload: [
+				{
+					relation: 'department',
+					columns: ['id', 'name'],
+				},
+			],
+			filters: [{ column: 'active', operator: 'eq', value: true }],
+			sort: [{ column: 'created_at', direction: 'desc' }],
+			computedColumns: [{ name: 'full_name', expression: "first_name || ' ' || last_name" }],
+			customOperators: [{ name: 'tenant', sql: "tenant_id = '123'" }],
+			parameters: [{ name: 'p_role', value: 'admin' }],
+		},
+	}}
+	height={480}
+	pageSize={50}
+/>
+```
+
+#### `dataSource` values
+
+| Value          | Adapter class                    | Transport          |
+|----------------|----------------------------------|--------------------|
+| `resolvespec`  | `GridlerResolveSpecAdapter`      | JSON request body  |
+| `headerspec`   | `GridlerRestHeaderSpecAdapter`   | HTTP headers       |
+
+#### `dataSourceOptions.extraOptions` — all fields
+
+These are `Partial<Options>` from `@warkypublic/resolvespec-js`. Grid-controlled values
+(sort, filters, limit, cursor, columns) always win over anything set here.
+
+| Field             | Type                  | Purpose                                                          |
+|-------------------|-----------------------|------------------------------------------------------------------|
+| `preload`         | `PreloadOption[]`     | Eager-load related entities. See `PreloadOption` fields below.   |
+| `omit_columns`    | `string[]`            | Exclude these columns from every response.                       |
+| `computedColumns` | `ComputedColumn[]`    | Server-side SQL expressions: `{ name, expression }`.             |
+| `customOperators` | `CustomOperator[]`    | Raw SQL WHERE fragments (AND-combined): `{ name, sql }`.         |
+| `parameters`      | `Parameter[]`         | Named query params: `{ name, value, sequence? }`.                |
+| `filters`         | `FilterOption[]`      | Default filters prepended before any grid column filters.        |
+| `sort`            | `SortOption[]`        | Default sort, overridden when the user clicks a column header.   |
+| `fetch_row_number`| `string`              | Column whose absolute row number is returned in metadata.        |
+| `offset`          | `number`              | Static row offset — avoid mixing with cursor pagination.         |
+
+##### `PreloadOption` key fields
+
+| Field                | Purpose                                              |
+|----------------------|------------------------------------------------------|
+| `relation`           | Relation name (required).                            |
+| `table_name`         | Override the table resolved from the relation.       |
+| `columns`            | Columns to select on the related table.              |
+| `omit_columns`       | Columns to exclude on the related table.             |
+| `filters`            | Filters applied to the related table.                |
+| `sort`               | Sort order for the related rows.                     |
+| `limit`              | Max related rows per parent row.                     |
+| `recursive`          | Self-referential recursive load.                     |
+| `primary_key`        | Override primary key used for the join.              |
+| `related_key`        | Foreign key on the related table.                    |
+| `foreign_key`        | Foreign key on the parent table.                     |
+| `recursive_child_key`| Key used for the recursive child join.               |
+| `sql_joins`          | Raw SQL JOIN clauses.                                |
+| `join_aliases`       | Aliases for the SQL joins.                           |
+| `computed_ql`        | Map of computed column name → SQL expression.        |
+| `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.
+- `hotfields` are fetched alongside column fields but not rendered — use them for fields needed by filters or computed logic.
+- Use `headerspec` when the API endpoint only accepts query options via HTTP headers instead of a JSON body.
+
 ### SvarkGrid: adapter-backed tabular data
 
 Based on:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warkypublic/svelix",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "Svelte 5 component library with Skeleton UI and Tailwind CSS",
   "license": "Apache-2.0",
   "exports": {
@@ -26,43 +26,43 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
-    "@chromatic-com/storybook": "^5.1.2",
-    "@eslint/compat": "^2.0.5",
+    "@chromatic-com/storybook": "^5.2.1",
+    "@eslint/compat": "^2.1.0",
     "@eslint/js": "^10.0.1",
-    "@playwright/test": "^1.59.1",
-    "@sentry/svelte": "^10.49.0",
+    "@playwright/test": "^1.60.0",
+    "@sentry/svelte": "^10.53.1",
     "@skeletonlabs/skeleton": "^4.15.2",
     "@skeletonlabs/skeleton-svelte": "^4.15.2",
-    "@storybook/addon-a11y": "^10.3.5",
-    "@storybook/addon-docs": "^10.3.5",
+    "@storybook/addon-a11y": "^10.4.0",
+    "@storybook/addon-docs": "^10.4.0",
     "@storybook/addon-svelte-csf": "^5.1.2",
-    "@storybook/addon-vitest": "^10.3.5",
-    "@storybook/sveltekit": "^10.3.5",
+    "@storybook/addon-vitest": "^10.4.0",
+    "@storybook/sveltekit": "^10.4.0",
     "@storybook/test": "^8.6.15",
     "@sveltejs/adapter-auto": "^7.0.1",
-    "@sveltejs/kit": "^2.57.1",
+    "@sveltejs/kit": "^2.60.1",
     "@sveltejs/package": "^2.5.7",
-    "@sveltejs/vite-plugin-svelte": "^7.0.0",
-    "@tailwindcss/vite": "^4.2.4",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@tailwindcss/vite": "^4.3.0",
     "@tanstack/svelte-virtual": "^3.13.24",
-    "@types/node": "^25.6.0",
-    "@vitest/browser-playwright": "^4.1.5",
-    "@vitest/coverage-v8": "^4.1.5",
-    "eslint": "^10.2.1",
+    "@types/node": "^25.8.0",
+    "@vitest/browser-playwright": "^4.1.6",
+    "@vitest/coverage-v8": "^4.1.6",
+    "eslint": "^10.4.0",
     "eslint-plugin-svelte": "^3.17.1",
-    "globals": "^17.5.0",
-    "playwright": "^1.59.1",
-    "publint": "^0.3.18",
-    "storybook": "^10.3.5",
-    "svelte": "^5.55.4",
-    "svelte-check": "^4.4.6",
-    "tailwindcss": "^4.2.4",
+    "globals": "^17.6.0",
+    "playwright": "^1.60.0",
+    "publint": "^0.3.21",
+    "storybook": "^10.4.0",
+    "svelte": "^5.55.7",
+    "svelte-check": "^4.4.8",
+    "tailwindcss": "^4.3.0",
     "tslib": "^2.8.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.0",
-    "vite": "^8.0.9",
+    "typescript-eslint": "^8.59.3",
+    "vite": "^8.0.13",
     "vite-plugin-monaco-editor": "^1.1.0",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.6"
   },
   "svelte": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -81,8 +81,8 @@
     "@warkypublic/artemis-kit": "^1.0.10",
     "carta-md": "^4.11.2",
     "github-markdown-css": "^5.9.0",
-    "isomorphic-dompurify": "^3.9.0",
-    "katex": "^0.16.45",
+    "isomorphic-dompurify": "^3.13.0",
+    "katex": "^0.16.47",
     "monaco-editor": "^0.55.1"
   },
   "scripts": {