@warkypublic/svelix 0.1.24 → 0.1.25

package/dist/components/SvarkGrid/SvarkGrid.svelte

@@ -174,6 +174,8 @@
 	let page = $state(0);
 	let reload = $state(0);
 	let lastServerRequestKey = $state<string>('');
+	let activeServerRequestId = 0;
+	let activeServerRequestKey = '';
 
 	let gridApi = $state<IApi | null>(null);
 	let searchOpen = $state(false);
@@ -504,6 +506,33 @@
 	let debouncedFilter = $state<SvarkFilterState>({});
 	let _debounceTimer: ReturnType<typeof setTimeout> | null = null;
 
+	function isSameSortState(a: SvarkSortState[], b: SvarkSortState[]): boolean {
+		if (a.length !== b.length) return false;
+		return a.every((item, index) => item.key === b[index]?.key && item.order === b[index]?.order);
+	}
+
+	function isSameFilterState(a: SvarkFilterState, b: SvarkFilterState): boolean {
+		const aKeys = Object.keys(a);
+		const bKeys = Object.keys(b);
+		if (aKeys.length !== bKeys.length) return false;
+
+		for (const key of aKeys) {
+			const left = a[key];
+			const right = b[key];
+			if (
+				!right ||
+				left?.column !== right.column ||
+				left?.operator !== right.operator ||
+				left?.logic_operator !== right.logic_operator ||
+				left?.value !== right.value
+			) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
 	$effect(() => {
 		const s = sortState;
 		const f = effectiveFilterState;
@@ -517,6 +546,9 @@
 		if (_debounceTimer !== null) clearTimeout(_debounceTimer);
 		_debounceTimer = setTimeout(() => {
 			_debounceTimer = null;
+			if (page === 0 && isSameSortState(debouncedSort, s) && isSameFilterState(debouncedFilter, f)) {
+				return;
+			}
 			page = 0; // reset page atomically — prevents a double-fetch
 			debouncedSort = s;
 			debouncedFilter = f;
@@ -626,6 +658,43 @@
 		emitFilters({});
 	}
 
+	function extractRowsFromResponse(response: unknown): Record<string, unknown>[] {
+		if (Array.isArray(response)) {
+			return response as Record<string, unknown>[];
+		}
+
+		if (
+			response &&
+			typeof response === 'object' &&
+			Array.isArray((response as { data?: unknown }).data)
+		) {
+			return (response as { data: Record<string, unknown>[] }).data;
+		}
+
+		return [];
+	}
+
+	function normalizeGridRows(rows: Record<string, unknown>[], uniqueID: string): Record<string, unknown>[] {
+		return rows.map((row) => {
+			const rowId = row?.id;
+			const uniqueValue = row?.[uniqueID];
+			if (rowId != null || uniqueValue == null) return row;
+			return { ...row, id: uniqueValue };
+		});
+	}
+
+	function extractTotalFromResponse(response: unknown, rows: Record<string, unknown>[]): number {
+		if (
+			response &&
+			typeof response === 'object' &&
+			typeof (response as { metadata?: { total?: unknown } }).metadata?.total === 'number'
+		) {
+			return (response as { metadata: { total: number } }).metadata.total;
+		}
+
+		return rows.length;
+	}
+
 	$effect(() => {
 		// Keep SVAR's local highlight + server-side search filters in sync with controlled searchValue.
 		const next = searchValueState;
@@ -725,9 +794,10 @@
 		// Paging offset: only applied when server-side paging is active
 		const _offset = showPager ? page * pageSize : 0;
 		void reload;
-		let cancelled = false;
 
 		if (!_adapter) {
+			activeServerRequestId += 1;
+			activeServerRequestKey = '';
 			loading = false;
 			error = resolvedServerSide
 				? 'Missing server configuration (dataSourceOptions.url/schema/entity)'
@@ -736,11 +806,10 @@
 			return;
 		}
 
-		loading = true;
-		error = null;
-
 		// Guard: if something upstream keeps re-triggering the effect without changing the
 		// actual server query parameters, avoid a tight refetch loop.
+		let requestId = 0;
+		let reqKey = '';
 		if (resolvedServerSide) {
 			const sortKey = JSON.stringify(_sort ?? []);
 			const filterKey = JSON.stringify(
@@ -749,7 +818,7 @@
 					.map((k) => [k, (_filters as any)[k]?.column, (_filters as any)[k]?.operator, (_filters as any)[k]?.value])
 			);
 			const queryKey = JSON.stringify(query ?? {});
-			const reqKey = JSON.stringify({
+			reqKey = JSON.stringify({
 				url: resolvedUrl,
 				schema: resolvedSchema,
 				entity: resolvedEntity,
@@ -763,19 +832,33 @@
 			});
 
 			if (reqKey === lastServerRequestKey) {
-				loading = false;
 				return;
 			}
+
 			lastServerRequestKey = reqKey;
+			activeServerRequestKey = reqKey;
+			activeServerRequestId += 1;
+			requestId = activeServerRequestId;
 		}
 
+		loading = true;
+		error = null;
+
 		_adapter
 			.read(_sort, _filters, _limit, _offset, query)
 			.then((response) => {
-				if (cancelled) return;
-				if (response.success) {
-					const incoming = response.data ?? [];
-					total = (response as any).metadata?.total ?? incoming.length;
+				if (
+					resolvedServerSide &&
+					(requestId !== activeServerRequestId || reqKey !== activeServerRequestKey)
+				) {
+					return;
+				}
+				if ((response as any)?.success !== false) {
+					const incoming = normalizeGridRows(
+						extractRowsFromResponse(response),
+						resolvedUniqueID
+					);
+					total = extractTotalFromResponse(response, incoming);
 
 					if (virtualScroll) {
 						data = [];
@@ -796,18 +879,24 @@
 				}
 			})
 			.catch((e) => {
-				if (cancelled) return;
+				if (
+					resolvedServerSide &&
+					(requestId !== activeServerRequestId || reqKey !== activeServerRequestKey)
+				) {
+					return;
+				}
 				const msg = e instanceof Error ? e.message : 'Unknown error';
 				error = msg;
 				onerror?.(msg);
 			})
 			.finally(() => {
-				if (!cancelled) loading = false;
+				if (
+					!resolvedServerSide ||
+					(requestId === activeServerRequestId && reqKey === activeServerRequestKey)
+				) {
+					loading = false;
+				}
 			});
-
-		return () => {
-			cancelled = true;
-		};
 	});
 
 	async function loadNextPage() {
@@ -841,8 +930,12 @@
 					return;
 				}
 			}
-			if (response.success) {
-				data = [...data, ...(response.data ?? [])];
+			if ((response as any)?.success !== false) {
+				const incoming = normalizeGridRows(
+					extractRowsFromResponse(response),
+					resolvedUniqueID
+				);
+				data = [...data, ...incoming];
 			}
 		} catch {
 			// Silent — don't replace existing rows with an error on pagination
@@ -885,8 +978,8 @@
 						start,
 						query
 					);
-					if (response.success) {
-						data = response.data ?? [];
+					if ((response as any)?.success !== false) {
+						data = normalizeGridRows(extractRowsFromResponse(response), resolvedUniqueID);
 					}
 				} catch (e) {
 					const msg = e instanceof Error ? e.message : 'Failed to load data';

package/llm/COMPONENT_GUIDE.md

@@ -373,6 +373,254 @@ Prefer stories that cover:
 - interactive behavior
 - any adapter-driven or async flow that is likely to regress
 
+## Implementation Examples From Stories
+
+These examples are adapted from the real Storybook stories in this repository. They are better reference points for LLM implementation work than generic placeholder snippets.
+
+### Former: request-driven form workflow
+
+Based on:
+- [src/lib/components/Former/Former.stories.ts](/home/hein/hein/dev/svelix/src/lib/components/Former/Former.stories.ts)
+
+```svelte
+<script lang="ts">
+	import { Former } from '@warkypublic/svelix';
+
+	export interface Props {
+		request?: 'insert' | 'update' | 'delete' | 'view';
+	}
+
+	let { request = 'insert' }: Props = $props();
+
+	let values = $state({
+		firstName: '',
+		lastName: '',
+		email: '',
+		role: 'viewer'
+	});
+
+	async function onAPICall(_mode: 'mutate' | 'read', req: string, value?: typeof values) {
+		if (req === 'select') {
+			return {
+				firstName: 'Janet',
+				lastName: 'Nguyen',
+				email: 'janet@example.com',
+				role: 'admin'
+			};
+		}
+
+		return value;
+	}
+</script>
+
+<Former {request} {values} {onAPICall}>
+	{#snippet children(state)}
+		<p>Request: {state.request}</p>
+		<p>Dirty: {state.dirty ? 'yes' : 'no'}</p>
+	{/snippet}
+</Former>
+```
+
+Story behavior worth preserving:
+- `insert` mode should allow saving immediately once required fields are valid
+- `update` mode should keep save disabled until the form becomes dirty
+- `delete` mode should require explicit confirmation before delete is enabled
+- modal and drawer variants should behave the same way once opened
+
+### Gridler: canvas-backed data grid
+
+Based on:
+- [src/lib/components/Gridler/components/Gridler.stories.ts](/home/hein/hein/dev/svelix/src/lib/components/Gridler/components/Gridler.stories.ts)
+
+```svelte
+<script lang="ts">
+	import { Gridler } from '@warkypublic/svelix';
+	import type { GridlerCell, GridlerColumn, Item } from '@warkypublic/svelix';
+
+	export interface Props {
+		height?: number;
+	}
+
+	let { height = 400 }: Props = $props();
+
+	const columns: GridlerColumn[] = [
+		{ id: 'name', title: 'Name', width: 180 },
+		{ id: 'email', title: 'Email', width: 220 },
+		{ id: 'age', title: 'Age', width: 80 }
+	];
+
+	function getCellContent([col, row]: Item): GridlerCell {
+		const person = {
+			name: `User ${row + 1}`,
+			email: `user${row + 1}@example.com`,
+			age: 20 + (row % 30)
+		};
+
+		if (col === 0) return { kind: 'text', data: person.name, displayData: person.name, allowOverlay: true };
+		if (col === 1) return { kind: 'uri', data: person.email, displayData: person.email, allowOverlay: true };
+		return { kind: 'number', data: person.age, displayData: String(person.age), allowOverlay: true };
+	}
+</script>
+
+<Gridler
+	{columns}
+	rows={1000}
+	{getCellContent}
+	{height}
+	rowMarkers="number"
+	searchValue="User 1"
+/>
+```
+
+Story behavior worth preserving:
+- support large row counts without rendering every row into the DOM
+- row markers can switch between `none`, `number`, and `checkbox`
+- search highlighting and fixed columns are first-class usage patterns
+- theme overrides are an expected integration point, not a niche feature
+
+### SvarkGrid: adapter-backed tabular data
+
+Based on:
+- [src/lib/components/SvarkGrid/SvarkGrid.stories.ts](/home/hein/hein/dev/svelix/src/lib/components/SvarkGrid/SvarkGrid.stories.ts)
+
+```svelte
+<script lang="ts">
+	import { SvarkGrid } from '@warkypublic/svelix';
+
+	const columns = [
+		{ id: 'id', title: 'ID', width: 60 },
+		{ id: 'name', title: 'Name', width: 180 },
+		{ id: 'email', title: 'Email', width: 220 },
+		{ id: 'role', title: 'Role', width: 100 }
+	];
+</script>
+
+<SvarkGrid
+	url="/api/users"
+	schema="public"
+	entity="users"
+	adapterType="ResolveSpec"
+	{columns}
+	pageSize={25}
+	serverSide={true}
+	height={480}
+	select={true}
+	multiselect={true}
+/>
+```
+
+Story behavior worth preserving:
+- both `ResolveSpec` and `RestHeaderSpec` style adapters are supported patterns
+- sorting, filtering, search, and selected-items callbacks are part of normal usage
+- mock adapters in stories are a good reference for test doubles and local prototyping
+
+### VTree: local or lazy-loaded tree data
+
+Based on:
+- [src/lib/components/VTree/VTree.stories.ts](/home/hein/hein/dev/svelix/src/lib/components/VTree/VTree.stories.ts)
+
+```svelte
+<script lang="ts">
+	import { VTree } from '@warkypublic/svelix';
+	import type { VTreeRecord, VTreeServerAdapter } from '@warkypublic/svelix';
+
+	export interface DemoNode extends VTreeRecord {
+		id: string;
+		label: string;
+		description?: string;
+		hasChildren?: boolean;
+	}
+
+	class DemoAdapter implements VTreeServerAdapter<DemoNode> {
+		async readRoot(): Promise<DemoNode[]> {
+			return [{ id: 'root-1', label: 'Root 1', hasChildren: true }];
+		}
+
+		async readChildren(node: DemoNode): Promise<DemoNode[]> {
+			return [{ id: `${node.id}-child-1`, label: `Child of ${node.label}` }];
+		}
+
+		async search(query: string): Promise<DemoNode[]> {
+			return [{ id: 'match-1', label: `Match: ${query}` }];
+		}
+	}
+
+	const adapter = new DemoAdapter();
+</script>
+
+<VTree
+	{adapter}
+	loadOnMount={true}
+	searchable={true}
+	serverSideSearch={true}
+	height={480}
+	rowHeight={36}
+/>
+```
+
+Story behavior worth preserving:
+- local data and adapter-driven data are equally valid entry points
+- server-side search is an explicit mode, not just a derived optimization
+- virtualization settings such as `rowHeight` and `overscan` matter for large trees
+
+### ContentEditor: file-type driven editor/viewer selection
+
+Based on:
+- [src/lib/components/ContentEditor/ContentEditor.stories.ts](/home/hein/hein/dev/svelix/src/lib/components/ContentEditor/ContentEditor.stories.ts)
+
+```svelte
+<script lang="ts">
+	import { ContentEditor } from '@warkypublic/svelix';
+
+	const markdown = new Blob(
+		[
+			`# Hello\n\nThis file is edited through the markdown flow.\n\n- Item one\n- Item two\n`
+		],
+		{ type: 'text/markdown' }
+	);
+
+	async function onUpload(file: File): Promise<string | null> {
+		return `/uploads/${file.name}`;
+	}
+</script>
+
+<ContentEditor
+	filename="notes.md"
+	value={markdown}
+	readonly={false}
+	{onUpload}
+/>
+```
+
+Story behavior worth preserving:
+- filename and content type drive editor selection
+- markdown, Monaco/text, media, and PDF flows are all real supported paths
+- office-document integrations expose `insertText` and `insertHtml` hooks for external automation
+
+### BetterMenu: interaction-first menu behavior
+
+Based on:
+- [src/lib/components/BetterMenu/BetterMenu.stories.ts](/home/hein/hein/dev/svelix/src/lib/components/BetterMenu/BetterMenu.stories.ts)
+
+```svelte
+<script lang="ts">
+	import { BetterMenu } from '@warkypublic/svelix';
+
+	export interface Props {
+		providerID?: string;
+	}
+
+	let { providerID = 'example-menu' }: Props = $props();
+</script>
+
+<BetterMenu {providerID} />
+```
+
+Story behavior worth preserving:
+- opening via an explicit trigger is the default interaction model
+- closing via Escape/backdrop is part of the expected behavior contract
+- interactive stories are a good source for keyboard and focus expectations
+
 ### Story with Actions
 ```typescript
 import { action } from '@storybook/addon-actions';

package/package.json

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