@katlux/providers 0.1.0-beta.0

package/services/DataProvider/CFlatClientDataProvider.ts

@@ -0,0 +1,52 @@
+import { ref, type Ref } from 'vue'
+import { ADataProvider } from './ADataProvider'
+import type { TDataRow, IDataFilter, IDataProviderOptions } from '../types'
+import { useFilterLogic } from '@katlux/toolkit/composables/useFilterLogic'
+import { useSortLogic } from '@katlux/toolkit/composables/useSortLogic'
+
+const { evaluateFilter, filterData } = useFilterLogic()
+const { sortData } = useSortLogic()
+
+
+export class CFlatClientDataProvider extends ADataProvider {
+	allData: Ref<TDataRow[]> = ref([])
+	filteredData: Ref<TDataRow[]> = ref([])
+
+	constructor(options?: IDataProviderOptions) {
+		super(options)
+	}
+
+	setData(data: TDataRow[]) {
+		this.allData.value = [...data]
+		this.loadPageData()
+	}
+
+	async loadPageData(): Promise<void> {
+
+		// Apply filters
+		if (!this.filter.value) {
+			this.filteredData.value = this.allData.value
+		} else {
+			const { results } = filterData(this.allData.value, this.filter.value)
+			this.filteredData.value = results
+		}
+		this.rowCount.value = this.filteredData.value.length
+
+		// Apply sort
+		if (this.sortList.value.length > 0)
+			this.filteredData.value = sortData(this.sortList.value, this.filteredData.value)
+		// Apply pagination (pageSize <= 0 means no pagination)
+		if (this.pageSize.value <= 0) {
+			this.pageData.value = this.filteredData.value
+		} else {
+			const startIndex = (this.currentPage.value - 1) * this.pageSize.value
+			const endIndex = startIndex + this.pageSize.value
+			this.pageData.value = this.filteredData.value.slice(startIndex, endIndex)
+		}
+	}
+
+	refreshData(): void {
+
+	}
+
+}

package/services/DataProvider/CFlatServerDataProvider.ts

@@ -0,0 +1,104 @@
+import { ref, type Ref } from 'vue'
+import { ADataProvider } from './ADataProvider'
+import type { TDataRow, IDataResult, TPageDataHandler, IDataFilter, IDataSort, IDataProviderOptions } from '../types'
+
+export class CFlatServerDataProvider extends ADataProvider {
+
+	pageDataHandler: Ref<TPageDataHandler> = ref((currentPage: number, pageSize: number, filter: IDataFilter, sortList: IDataSort[]): IDataResult | Promise<IDataResult> => {
+		return {
+			rows: [],
+			rowCount: 0
+		};
+	})
+	contextKey: Ref<string> = ref("")
+	initialLoad: Ref<boolean> = ref(true)
+
+	constructor(options?: IDataProviderOptions) {
+		super(options)
+	}
+
+	setContextKey(key: string) {
+		this.contextKey.value = key
+	}
+
+	async setPageDataHandler(handler: TPageDataHandler) {
+		this.pageDataHandler.value = handler
+		await this.loadPageData()
+	}
+
+	async loadPageData(options?: { disableCache?: boolean }): Promise<void> {
+
+
+		if (!this.pageDataHandler.value || (!this.SSR.value && import.meta.server)) return;
+
+		// Stable key generation for Nuxt hydration
+		const stableStringify = (val: any) => JSON.stringify(val === undefined ? "" : val)
+		const key = [
+			this.contextKey.value,
+			this.currentPage.value,
+			this.pageSize.value,
+			stableStringify(this.filter.value),
+			stableStringify(this.sortList.value)
+		].join('-')
+
+		const fetcher = async () => await this.pageDataHandler.value(this.currentPage.value, this.pageSize.value, this.filter.value as IDataFilter, this.sortList.value as IDataSort[], options)
+
+
+		// Check for existing data from SSR payload first (Only if SSR is enabled)
+		// Skip if disableCache is true
+		if (!options?.disableCache && this.SSR.value && this.contextKey.value && this.initialLoad.value) {
+			const { data } = useNuxtData(key)
+			if (data.value) {
+				const result = data.value as IDataResult
+				this.pageData.value = result.rows
+				this.rowCount.value = result.rowCount
+				this.initialLoad.value = false
+				this.loading.value = false
+				return
+			}
+		}
+
+		// SSR: use useAsyncData when SSR is enabled (works on both server and client)
+		if (this.SSR.value && this.contextKey.value) {
+			this.loading.value = true
+			const { data } = await useAsyncData(key, fetcher)
+			if (data.value) {
+				const result = data.value as IDataResult
+				this.pageData.value = result.rows
+				this.rowCount.value = result.rowCount
+				this.initialLoad.value = false
+				this.loading.value = false
+				return
+			}
+		}
+
+		// For non-SSR client-side, handle asynchronously without blocking
+		if (!this.SSR.value) {
+			// Call fetcher and handle promise asynchronously after Nuxt is ready (hydrated)
+			// This avoids hydration mismatches on initial load
+			onNuxtReady(() => {
+				this.loading.value = true
+				fetcher().then((returnedData) => {
+					this.pageData.value = returnedData.rows
+					this.rowCount.value = returnedData.rowCount
+					this.initialLoad.value = false
+					this.loading.value = false
+				}).catch(() => {
+					this.initialLoad.value = false
+					this.loading.value = false
+				})
+			})
+			return
+		}
+
+		// SSR client-side or fallback: await the request
+		this.loading.value = true
+		const returnedData: IDataResult = await fetcher()
+		this.pageData.value = returnedData.rows
+		this.rowCount.value = returnedData.rowCount
+		this.initialLoad.value = false
+		this.loading.value = false
+
+	}
+
+}

package/services/DataProvider/CTreeClientDataProvider.ts

@@ -0,0 +1,335 @@
+import { ref, computed, watch, type Ref, type ComputedRef } from 'vue'
+import { CFlatClientDataProvider } from './CFlatClientDataProvider'
+import { useFilterLogic } from '@katlux/toolkit/composables/useFilterLogic'
+import type {
+	TDataRow,
+	ITreeNode,
+	ITreeNodeStatic,
+	TreePaginationMode,
+	ITreeDataProviderOptions
+} from '../types'
+
+const { evaluateFilter, filterData } = useFilterLogic()
+
+
+export class CTreeClientDataProvider extends CFlatClientDataProvider {
+	// Tree configuration
+	parentKey: string = 'parentId'
+	idKey: string = 'id'
+	expandedByDefault: boolean = false
+	paginateBy: TreePaginationMode = 'all'
+
+	// Tree state
+	expandedNodes: Ref<Set<string | number>> = ref(new Set())
+
+	// Internal: static tree structure (only rebuilds when data changes)
+	private _staticNodes: ComputedRef<ITreeNodeStatic[]>
+	private _nodeMap: ComputedRef<Map<string | number, ITreeNodeStatic>>
+	private _sortedNodeIds: ComputedRef<(string | number)[]>
+
+	constructor(options?: ITreeDataProviderOptions) {
+		super(options)
+		if (options?.parentKey) this.parentKey = options.parentKey
+		if (options?.idKey) this.idKey = options.idKey
+		if (options?.expandedByDefault) this.expandedByDefault = options.expandedByDefault
+		if (options?.paginateBy) this.paginateBy = options.paginateBy
+
+		// Static tree structure - only rebuilds when allData changes
+		this._staticNodes = computed(() => this.buildStaticNodes())
+		this._nodeMap = computed(() => new Map(this._staticNodes.value.map(n => [n.id, n])))
+		this._sortedNodeIds = computed(() => this.computeSortedIds())
+
+		// Watch for changes that require pageData update
+		// Note: currentPage and pageSize changes are handled by parent ADataProvider watchers
+		// which call loadPageData() -> updatePageData()
+		watch([this.expandedNodes, this._staticNodes], () => {
+			this.updatePageData()
+		}, { immediate: true })
+	}
+
+	private buildStaticNodes(): ITreeNodeStatic[] {
+		const allData = this.allData.value || []
+		const nodeMap = new Map<string | number, ITreeNodeStatic>()
+		const childrenMap = new Map<string | number, TDataRow[]>()
+
+		// First pass: create nodes and map children
+		allData.forEach((item: TDataRow) => {
+			const id = item[this.idKey]
+			const parentId = item[this.parentKey] || null
+
+			nodeMap.set(id, {
+				data: item,
+				id,
+				parentId,
+				depth: 0,
+				hasChildren: false,
+			})
+
+			if (parentId !== null) {
+				if (!childrenMap.has(parentId)) {
+					childrenMap.set(parentId, [])
+				}
+				childrenMap.get(parentId)!.push(item)
+			}
+		})
+
+		// Second pass: set hasChildren and calculate depth
+		const calculateDepth = (nodeId: string | number, depth: number = 0): void => {
+			const node = nodeMap.get(nodeId)
+			if (!node) return
+
+			node.depth = depth
+			const children = childrenMap.get(nodeId)
+			if (children && children.length > 0) {
+				node.hasChildren = true
+				children.forEach((child: TDataRow) => {
+					calculateDepth(child[this.idKey], depth + 1)
+				})
+			}
+		}
+
+		nodeMap.forEach((node) => {
+			if (node.parentId === null) {
+				calculateDepth(node.id, 0)
+			}
+		})
+
+		return Array.from(nodeMap.values())
+	}
+
+	// Pre-compute sorted order once (only when data changes)
+	private computeSortedIds(): (string | number)[] {
+		const nodes = this._staticNodes.value
+		const nodeMap = new Map(nodes.map(n => [n.id, n]))
+
+		// Build tree order using DFS
+		const sortedIds: (string | number)[] = []
+		const rootNodes = nodes.filter(n => n.parentId === null)
+
+		// Get children map
+		const childrenMap = new Map<string | number, ITreeNodeStatic[]>()
+		nodes.forEach(n => {
+			if (n.parentId !== null) {
+				if (!childrenMap.has(n.parentId)) {
+					childrenMap.set(n.parentId, [])
+				}
+				childrenMap.get(n.parentId)!.push(n)
+			}
+		})
+
+		const collectNodes = (node: ITreeNodeStatic): void => {
+			sortedIds.push(node.id)
+			const children = childrenMap.get(node.id) || []
+			children.forEach(child => collectNodes(child))
+		}
+
+		rootNodes.forEach(root => collectNodes(root))
+		return sortedIds
+	}
+
+	// Fast visibility check and page data update
+	private updatePageData(): void {
+		const nodeMap = this._nodeMap.value
+		const sortedIds = this._sortedNodeIds.value
+		const visibleNodes: ITreeNode[] = []
+
+		if (this.filter.value && this.filter.value.active) {
+			// FILTER LOGIC
+			// Use shared filterData with treeOptions
+			// Static nodes are already in flat format needed
+			const { results: filtered, expandedNodes: expandedResults } = filterData(
+				this._staticNodes.value,
+				this.filter.value,
+				{
+					treeOptions: {
+						idKey: this.idKey,
+						parentKey: this.parentKey
+					}
+				}
+			)
+
+			// We need to update isExpanded based on the result
+			const expandedSet = expandedResults || new Set()
+			for (const node of (filtered as ITreeNodeStatic[])) {
+				visibleNodes.push({
+					...node,
+					isExpanded: expandedSet.has(node.id)
+				})
+			}
+
+		} else {
+			// STANDARD TREE VISIBILITY LOGIC
+			for (const id of sortedIds) {
+				const staticNode = nodeMap.get(id)
+				if (!staticNode) continue
+
+				// Check if node is visible (all ancestors expanded)
+				if (this.isNodeVisible(staticNode, nodeMap)) {
+					const isExpanded = this.expandedByDefault
+						? !this.expandedNodes.value.has(id)
+						: this.expandedNodes.value.has(id)
+
+					visibleNodes.push({
+						...staticNode,
+						isExpanded
+					})
+				}
+			}
+		}
+
+		// Apply pagination
+		const paginatedNodes = this.paginateNodes(visibleNodes)
+
+		// Update pageData for KDatatable
+		this.pageData.value = paginatedNodes.map(node => ({
+			...node.data,
+			__treeNode: node
+		}))
+	}
+
+	private isNodeVisible(node: ITreeNodeStatic, nodeMap: Map<string | number, ITreeNodeStatic>): boolean {
+		if (node.parentId === null) return true
+
+		let currentId: string | number | null = node.parentId
+		while (currentId !== null) {
+			const parent = nodeMap.get(currentId)
+			if (!parent) return false
+
+			const parentExpanded = this.expandedByDefault
+				? !this.expandedNodes.value.has(currentId)
+				: this.expandedNodes.value.has(currentId)
+
+			if (!parentExpanded) return false
+			currentId = parent.parentId
+		}
+		return true
+	}
+
+	private paginateNodes(visible: ITreeNode[]): ITreeNode[] {
+		const pageSize = this.pageSize.value
+		const currentPage = this.currentPage.value
+
+		// pageSize <= 0 means no pagination
+		if (pageSize <= 0) {
+			this.rowCount.value = visible.length
+			return visible
+		}
+
+		if (this.paginateBy === 'root') {
+			const rootNodes = visible.filter(n => n.parentId === null)
+			const startIndex = (currentPage - 1) * pageSize
+			const endIndex = startIndex + pageSize
+			const paginatedRoots = rootNodes.slice(startIndex, endIndex)
+			const paginatedRootIds = new Set(paginatedRoots.map(n => n.id))
+
+			const nodeMap = new Map(visible.map(n => [n.id, n]))
+			const getRootId = (node: ITreeNode): string | number => {
+				let current = node
+				while (current.parentId !== null) {
+					const parent = nodeMap.get(current.parentId as string | number)
+					if (!parent) break
+					current = parent
+				}
+				return current.id
+			}
+
+			const result = visible.filter(node => paginatedRootIds.has(getRootId(node)))
+			this.rowCount.value = rootNodes.length
+			return result
+		} else {
+			const startIndex = (currentPage - 1) * pageSize
+			const endIndex = startIndex + pageSize
+			this.rowCount.value = visible.length
+			return visible.slice(startIndex, endIndex)
+		}
+	}
+
+	// Override loadPageData
+	override async loadPageData(): Promise<void> {
+		this.updatePageData()
+	}
+
+	// Public API
+	get treeNodes(): ITreeNode[] {
+		// Build full tree nodes with expansion state
+		return this._staticNodes.value.map(node => ({
+			...node,
+			isExpanded: this.expandedByDefault
+				? !this.expandedNodes.value.has(node.id)
+				: this.expandedNodes.value.has(node.id)
+		}))
+	}
+
+	get visibleRows(): ITreeNode[] {
+		// Rebuild visible list
+		const nodeMap = this._nodeMap.value
+		const sortedIds = this._sortedNodeIds.value
+		const visibleNodes: ITreeNode[] = []
+
+		for (const id of sortedIds) {
+			const staticNode = nodeMap.get(id)
+			if (!staticNode) continue
+
+			if (this.isNodeVisible(staticNode, nodeMap)) {
+				visibleNodes.push({
+					...staticNode,
+					isExpanded: this.expandedByDefault
+						? !this.expandedNodes.value.has(id)
+						: this.expandedNodes.value.has(id)
+				})
+			}
+		}
+
+		return this.paginateNodes(visibleNodes)
+	}
+
+	toggleNode(nodeId: string | number): void {
+		if (this.expandedNodes.value.has(nodeId)) {
+			this.expandedNodes.value.delete(nodeId)
+		} else {
+			this.expandedNodes.value.add(nodeId)
+		}
+		// Trigger reactivity
+		this.expandedNodes.value = new Set(this.expandedNodes.value)
+	}
+
+	expand(nodeId: string | number): void {
+		this.expandedNodes.value.add(nodeId)
+		this.expandedNodes.value = new Set(this.expandedNodes.value)
+	}
+
+	collapse(nodeId: string | number): void {
+		this.expandedNodes.value.delete(nodeId)
+		this.expandedNodes.value = new Set(this.expandedNodes.value)
+	}
+
+	expandAll(): void {
+		const allIds = this._staticNodes.value.filter(n => n.hasChildren).map(n => n.id)
+		this.expandedNodes.value = new Set(allIds)
+	}
+
+	collapseAll(): void {
+		this.expandedNodes.value = new Set()
+	}
+
+	getNode(nodeId: string | number): ITreeNode | undefined {
+		const staticNode = this._nodeMap.value.get(nodeId)
+		if (!staticNode) return undefined
+		return {
+			...staticNode,
+			isExpanded: this.expandedByDefault
+				? !this.expandedNodes.value.has(nodeId)
+				: this.expandedNodes.value.has(nodeId)
+		}
+	}
+
+	getChildren(nodeId: string | number): ITreeNode[] {
+		return this.treeNodes.filter(n => n.parentId === nodeId)
+	}
+
+	getParent(nodeId: string | number): ITreeNode | undefined {
+		const node = this.getNode(nodeId)
+		if (!node || node.parentId === null) return undefined
+		return this.getNode(node.parentId)
+	}
+}

package/services/DataProvider/CTreeServerDataProvider.ts

@@ -0,0 +1,207 @@
+import { ref, watch, type Ref } from 'vue'
+import { ADataProvider } from './ADataProvider'
+import type {
+	IDataResult,
+	IDataFilter,
+	IDataSort,
+	ITreeDataProviderOptions,
+	TreePaginationMode
+} from '../types'
+
+/**
+ * Tree-specific page data handler that includes tree parameters
+ * Server handles tree building, visibility, and pagination
+ */
+export type TTreePageDataHandler = (
+	currentPage: number,
+	pageSize: number,
+	filter: IDataFilter,
+	sortList: IDataSort[],
+	treeParams: {
+		expandedNodes: (string | number)[],
+		parentKey: string,
+		idKey: string,
+		paginateBy: TreePaginationMode,
+		expandedByDefault: boolean
+	},
+	options?: { disableCache?: boolean }
+) => IDataResult | Promise<IDataResult>;
+
+/**
+ * Server-side Tree Data Provider
+ * 
+ * Key difference from CTreeClientDataProvider:
+ * - Tree structure, visibility, and pagination are handled SERVER-SIDE
+ * - Client only sends expanded state to server
+ * - Server returns already-paginated visible rows with __treeNode metadata
+ * - No allData - server handles everything
+ */
+export class CTreeServerDataProvider extends ADataProvider {
+	// Tree configuration (sent to server)
+	parentKey: string = 'parentId'
+	idKey: string = 'id'
+	expandedByDefault: boolean = false
+	paginateBy: TreePaginationMode = 'all'
+
+	// Tree state - toggled nodes (sent to server for visibility calculation)
+	expandedNodes: Ref<Set<string | number>> = ref(new Set())
+
+	// Server-side data handler
+	pageDataHandler: Ref<TTreePageDataHandler | null> = ref(null)
+	contextKey: Ref<string> = ref("")
+	initialLoad: Ref<boolean> = ref(true)
+
+	constructor(options?: ITreeDataProviderOptions) {
+		super(options)
+		if (options?.parentKey) this.parentKey = options.parentKey
+		if (options?.idKey) this.idKey = options.idKey
+		if (options?.expandedByDefault) this.expandedByDefault = options.expandedByDefault
+		if (options?.paginateBy) this.paginateBy = options.paginateBy
+
+		// Watch for changes that require server refetch
+		watch([this.expandedNodes, this.currentPage, this.pageSize], () => {
+			if (this.pageDataHandler.value && !this.initialLoad.value) {
+				this.loadPageData()
+			}
+		})
+	}
+
+	setContextKey(key: string) {
+		this.contextKey.value = key
+	}
+
+	async setPageDataHandler(handler: TTreePageDataHandler) {
+		this.pageDataHandler.value = handler
+		await this.loadPageData()
+	}
+
+	/**
+	 * Load page data from server
+	 * Server handles tree building, visibility, and pagination
+	 */
+	async loadPageData(options?: { disableCache?: boolean }): Promise<void> {
+		if (!this.pageDataHandler.value || (!this.SSR.value && import.meta.server)) return;
+
+		const expandedArray = Array.from(this.expandedNodes.value)
+		const stableStringify = (val: any) => JSON.stringify(val === undefined ? "" : val)
+		const key = [
+			this.contextKey.value,
+			this.currentPage.value,
+			this.pageSize.value,
+			stableStringify(this.filter.value),
+			stableStringify(this.sortList.value),
+			stableStringify(expandedArray)
+		].join('-')
+
+		const treeParams = {
+			expandedNodes: expandedArray,
+			parentKey: this.parentKey,
+			idKey: this.idKey,
+			paginateBy: this.paginateBy,
+			expandedByDefault: this.expandedByDefault
+		}
+
+		const fetcher = async () => await this.pageDataHandler.value!(
+			this.currentPage.value,
+			this.pageSize.value,
+			this.filter.value as IDataFilter,
+			this.sortList.value as IDataSort[],
+			treeParams,
+			options
+		)
+
+		// Check for existing data from SSR payload first
+		// Skip if disableCache is true
+		if (!options?.disableCache && this.SSR.value && this.contextKey.value && this.initialLoad.value) {
+			const { data } = useNuxtData(key)
+			if (data.value) {
+				const result = data.value as IDataResult
+				this.pageData.value = result.rows
+				this.rowCount.value = result.rowCount
+				this.initialLoad.value = false
+				this.loading.value = false
+				return
+			}
+		}
+
+		// SSR: use useAsyncData
+		if (this.SSR.value && this.contextKey.value) {
+			this.loading.value = true
+
+			// If cache is disabled, we bypass useAsyncData's automatic caching if possible, 
+			// but useAsyncData is primary for hydration. 
+			// For specific disableCache request in SSR mode, we might want to just fetch directly 
+			// OR rely on the fact that the underlying handler will disable cache.
+			// However, useAsyncData itself caches based on key. 
+			// If disableCache is true, we should probably append a random key or manage it otherwise?
+			// Actually, if disableCache is true, we likely shouldn't use useAsyncData at all if we want to force refresh?
+			// But sticking to standard pattern:
+			const { data } = await useAsyncData(key, fetcher)
+			if (data.value) {
+				const result = data.value as IDataResult
+				this.pageData.value = result.rows
+				this.rowCount.value = result.rowCount
+				this.initialLoad.value = false
+				this.loading.value = false
+				return
+			}
+		}
+
+		// Non-SSR client-side
+		if (!this.SSR.value) {
+			onNuxtReady(() => {
+				this.loading.value = true
+				fetcher().then((returnedData) => {
+					this.pageData.value = returnedData.rows
+					this.rowCount.value = returnedData.rowCount
+					this.initialLoad.value = false
+					this.loading.value = false
+				}).catch(() => {
+					this.initialLoad.value = false
+					this.loading.value = false
+				})
+			})
+			return
+		}
+
+		// Fallback
+		this.loading.value = true
+		const returnedData: IDataResult = await fetcher()
+		this.pageData.value = returnedData.rows
+		this.rowCount.value = returnedData.rowCount
+		this.initialLoad.value = false
+		this.loading.value = false
+	}
+
+	// ============================================
+	// Expand/Collapse API
+	// ============================================
+
+	toggleNode(nodeId: string | number): void {
+		if (this.expandedNodes.value.has(nodeId)) {
+			this.expandedNodes.value.delete(nodeId)
+		} else {
+			this.expandedNodes.value.add(nodeId)
+		}
+		this.expandedNodes.value = new Set(this.expandedNodes.value)
+	}
+
+	expand(nodeId: string | number): void {
+		this.expandedNodes.value.add(nodeId)
+		this.expandedNodes.value = new Set(this.expandedNodes.value)
+	}
+
+	collapse(nodeId: string | number): void {
+		this.expandedNodes.value.delete(nodeId)
+		this.expandedNodes.value = new Set(this.expandedNodes.value)
+	}
+
+	collapseAll(): void {
+		this.expandedNodes.value = new Set()
+	}
+
+	isExpanded(nodeId: string | number): boolean {
+		const isToggled = this.expandedNodes.value.has(nodeId)
+		return this.expandedByDefault ? !isToggled : isToggled
+	}
+}