@mohsinonxrm/pptb-fetchxml-studio 1.0.0

package/src/shared/components/RelationshipPicker.tsx

@@ -0,0 +1,268 @@
+/**
+ * Shared Relationship Picker component using Fluent UI v9 Combobox
+ * Loads relationships from metadata and displays categorized by type (1:N, N:1, N:N)
+ */
+
+import { useState, useEffect } from "react";
+import {
+	Combobox,
+	Option,
+	OptionGroup,
+	useId,
+	Spinner,
+	type ComboboxProps,
+} from "@fluentui/react-components";
+import { debugLog } from "../utils/debug";
+import { loadEntityRelationships } from "../../features/fetchxml/api/dataverseMetadata";
+import type { RelationshipMetadata } from "../../features/fetchxml/api/pptbClient";
+
+interface RelationshipOption {
+	schemaName: string;
+	displayText: string;
+	referencedEntity: string;
+	referencingEntity: string;
+	referencedAttribute: string;
+	referencingAttribute: string;
+	type: "1N" | "N1" | "NN";
+	category: string;
+}
+
+interface RelationshipPickerProps {
+	entityLogicalName: string;
+	value?: string; // SchemaName of selected relationship
+	onChange: (relationship: RelationshipOption) => void;
+	placeholder?: string;
+	disabled?: boolean;
+}
+
+export function RelationshipPicker({
+	entityLogicalName,
+	value,
+	onChange,
+	placeholder = "Select a relationship",
+	disabled = false,
+}: RelationshipPickerProps) {
+	const comboId = useId("relationship-combobox");
+	const [relationships, setRelationships] = useState<RelationshipOption[]>([]);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+	const [query, setQuery] = useState<string>("");
+
+	// Load relationships when entity changes
+	useEffect(() => {
+		if (!entityLogicalName) {
+			debugLog("relationshipPicker", "No entity name provided, clearing relationships");
+			setRelationships([]);
+			return;
+		}
+
+		debugLog("relationshipPicker", "Loading relationships for entity:", entityLogicalName);
+		setLoading(true);
+		setError(null);
+
+		loadEntityRelationships(entityLogicalName)
+			.then((data) => {
+				debugLog("relationshipPicker", "Received relationship data:", {
+					entityLogicalName,
+					oneToManyCount: data.oneToMany.length,
+					manyToOneCount: data.manyToOne.length,
+					manyToManyCount: data.manyToMany.length,
+				});
+
+				const options: RelationshipOption[] = [];
+
+				// Process 1:N relationships (current entity is Referenced/parent)
+				data.oneToMany.forEach((rel: RelationshipMetadata) => {
+					// Show: childEntity → parentEntity via lookupField (SchemaName)
+					const lookupField = rel.ReferencingAttribute || "";
+					const displayText = lookupField
+						? `${rel.ReferencingEntity} → ${rel.ReferencedEntity} via ${lookupField} (${rel.SchemaName})`
+						: `${rel.ReferencingEntity} → ${rel.ReferencedEntity} (${rel.SchemaName})`;
+
+					options.push({
+						schemaName: rel.SchemaName,
+						displayText,
+						referencedEntity: rel.ReferencedEntity,
+						referencingEntity: rel.ReferencingEntity,
+						referencedAttribute: rel.ReferencedAttribute,
+						referencingAttribute: rel.ReferencingAttribute,
+						type: "1N",
+						category: "One-to-Many (1:N)",
+					});
+				});
+
+				// Process N:1 relationships (current entity is Referencing/child)
+				data.manyToOne.forEach((rel: RelationshipMetadata) => {
+					// Show: childEntity → parentEntity via lookupField (SchemaName)
+					const lookupField = rel.ReferencingAttribute || "";
+					const displayText = lookupField
+						? `${rel.ReferencingEntity} → ${rel.ReferencedEntity} via ${lookupField} (${rel.SchemaName})`
+						: `${rel.ReferencingEntity} → ${rel.ReferencedEntity} (${rel.SchemaName})`;
+
+					options.push({
+						schemaName: rel.SchemaName,
+						displayText,
+						referencedEntity: rel.ReferencedEntity,
+						referencingEntity: rel.ReferencingEntity,
+						referencedAttribute: rel.ReferencedAttribute,
+						referencingAttribute: rel.ReferencingAttribute,
+						type: "N1",
+						category: "Many-to-One (N:1)",
+					});
+				});
+
+				// Process N:N relationships
+				data.manyToMany.forEach((rel: RelationshipMetadata) => {
+					// N:N relationships have Entity1/Entity2, not Referencing/Referenced
+					const entity1 = rel.Entity1LogicalName || "";
+					const entity2 = rel.Entity2LogicalName || "";
+					const attr1 = rel.Entity1IntersectAttribute || "";
+					const attr2 = rel.Entity2IntersectAttribute || "";
+
+					options.push({
+						schemaName: rel.SchemaName,
+						displayText: `${entity1} ↔ ${entity2} (${rel.SchemaName})`,
+						referencedEntity: entity2, // Store entity2 as "referenced" for compatibility
+						referencingEntity: entity1, // Store entity1 as "referencing" for compatibility
+						referencedAttribute: attr2,
+						referencingAttribute: attr1,
+						type: "NN",
+						category: "Many-to-Many (N:N)",
+					});
+				});
+
+				setRelationships(options);
+				setLoading(false);
+				debugLog("relationshipPicker", "Relationships loaded successfully:", {
+					entityLogicalName,
+					totalRelationships: options.length,
+				});
+			})
+			.catch((err: unknown) => {
+				console.error("[RelationshipPicker] Failed to load relationships:", {
+					entityLogicalName,
+					error: err,
+				});
+				setError("Failed to load relationships");
+				setLoading(false);
+			});
+	}, [entityLogicalName]);
+
+	// Sync query with selected value
+	useEffect(() => {
+		if (value) {
+			const rel = relationships.find((r) => r.schemaName === value);
+			if (rel) {
+				setQuery(rel.displayText);
+			} else {
+				setQuery(value);
+			}
+		} else {
+			setQuery("");
+		}
+	}, [value, relationships]);
+
+	// Manual filtering that preserves grouping
+	const filteredRelationships = query.trim()
+		? relationships.filter(
+				(rel) =>
+					rel.displayText.toLowerCase().includes(query.toLowerCase()) ||
+					rel.schemaName.toLowerCase().includes(query.toLowerCase()) ||
+					rel.referencingAttribute.toLowerCase().includes(query.toLowerCase())
+		  )
+		: relationships;
+
+	// Group by category
+	const categories = {
+		"One-to-Many (1:N)": filteredRelationships.filter((r) => r.category === "One-to-Many (1:N)"),
+		"Many-to-One (N:1)": filteredRelationships.filter((r) => r.category === "Many-to-One (N:1)"),
+		"Many-to-Many (N:N)": filteredRelationships.filter((r) => r.category === "Many-to-Many (N:N)"),
+	};
+
+	const onOptionSelect: ComboboxProps["onOptionSelect"] = (_e, data) => {
+		const schemaName = data.optionValue;
+		debugLog("relationshipPicker", "Relationship selected:", {
+			schemaName,
+			optionText: data.optionText,
+		});
+
+		if (schemaName) {
+			const rel = relationships.find((r) => r.schemaName === schemaName);
+			if (rel) {
+				debugLog("relationshipPicker", "Found relationship details:", rel);
+				setQuery(data.optionText ?? "");
+				onChange(rel);
+			}
+		} else {
+			// Handle clear
+			setQuery("");
+		}
+	};
+
+	if (loading) {
+		return <Spinner size="tiny" label="Loading relationships..." />;
+	}
+
+	if (error) {
+		return (
+			<Combobox
+				aria-labelledby={comboId}
+				value=""
+				placeholder="Error loading relationships"
+				disabled={true}
+			/>
+		);
+	}
+
+	return (
+		<Combobox
+			aria-labelledby={comboId}
+			value={query}
+			onOptionSelect={onOptionSelect}
+			onChange={(ev) => setQuery(ev.target.value)}
+			placeholder={
+				loading
+					? "Loading relationships..."
+					: relationships.length === 0
+					? "No relationships found"
+					: placeholder
+			}
+			disabled={disabled || loading || relationships.length === 0}
+			clearable
+		>
+			{filteredRelationships.length === 0 && query.trim() ? (
+				<Option disabled>No relationships match your search</Option>
+			) : (
+				<>
+					{categories["One-to-Many (1:N)"].length > 0 && (
+						<OptionGroup label="One-to-Many (1:N)">
+							{categories["One-to-Many (1:N)"].map((rel) => (
+								<Option key={rel.schemaName} value={rel.schemaName}>
+									{rel.displayText}
+								</Option>
+							))}
+						</OptionGroup>
+					)}
+					{categories["Many-to-One (N:1)"].length > 0 && (
+						<OptionGroup label="Many-to-One (N:1)">
+							{categories["Many-to-One (N:1)"].map((rel) => (
+								<Option key={rel.schemaName} value={rel.schemaName}>
+									{rel.displayText}
+								</Option>
+							))}
+						</OptionGroup>
+					)}
+					{categories["Many-to-Many (N:N)"].length > 0 && (
+						<OptionGroup label="Many-to-Many (N:N)">
+							{categories["Many-to-Many (N:N)"].map((rel) => (
+								<Option key={rel.schemaName} value={rel.schemaName}>
+									{rel.displayText}
+								</Option>
+							))}
+						</OptionGroup>
+					)}
+				</>
+			)}
+		</Combobox>
+	);
+}

package/src/shared/contexts/ThemeContext.tsx

@@ -0,0 +1,19 @@
+/**
+ * Theme context for accessing dark/light mode throughout the app
+ */
+
+import { createContext, useContext, type ReactNode } from "react";
+
+interface ThemeContextValue {
+	isDark: boolean;
+}
+
+const ThemeContext = createContext<ThemeContextValue>({ isDark: false });
+
+export function ThemeProvider({ isDark, children }: { isDark: boolean; children: ReactNode }) {
+	return <ThemeContext.Provider value={{ isDark }}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): ThemeContextValue {
+	return useContext(ThemeContext);
+}

package/src/shared/hooks/useAccessMode.ts

@@ -0,0 +1,77 @@
+/**
+ * Hook to determine user's access mode based on privileges
+ * Checks WhoAmI and privilege checks on mount
+ * Preloads all entity metadata if user has customization access
+ */
+
+import { useState, useEffect } from "react";
+import {
+	getAccessSummary,
+	getAllAdvancedFindEntities,
+	type AccessSummary,
+} from "../../features/fetchxml/api/pptbClient";
+
+export function useAccessMode() {
+	const [accessSummary, setAccessSummary] = useState<AccessSummary | null>(null);
+	const [loading, setLoading] = useState(true);
+	const [error, setError] = useState<string | null>(null);
+
+	useEffect(() => {
+		let mounted = true;
+
+		async function checkAccess() {
+			try {
+				setLoading(true);
+				setError(null);
+
+				const summary = await getAccessSummary();
+
+				if (mounted) {
+					setAccessSummary(summary);
+
+					// Preload all entity metadata if user has customization access
+					if (summary && !summary.noAccessMode) {
+						console.log("[useAccessMode] Preloading all entity metadata...");
+						getAllAdvancedFindEntities()
+							.then((entities) => {
+								console.log(
+									"[useAccessMode] Entity metadata preloaded:",
+									entities.length,
+									"entities"
+								);
+							})
+							.catch((err) => {
+								console.error("[useAccessMode] Failed to preload entity metadata:", err);
+							});
+					}
+				}
+			} catch (err) {
+				if (mounted) {
+					setError(err instanceof Error ? err.message : String(err));
+				}
+			} finally {
+				if (mounted) {
+					setLoading(false);
+				}
+			}
+		}
+
+		checkAccess();
+
+		return () => {
+			mounted = false;
+		};
+	}, []);
+
+	return {
+		accessSummary,
+		loading,
+		error,
+		// Convenience flags
+		fullFilterMode: accessSummary?.fullFilterMode ?? false,
+		solutionsOnlyMode: accessSummary?.solutionsOnlyMode ?? false,
+		publishersOnlyMode: accessSummary?.publishersOnlyMode ?? false,
+		metadataOnlyMode: accessSummary?.metadataOnlyMode ?? false,
+		noAccessMode: accessSummary?.noAccessMode ?? false,
+	};
+}

package/src/shared/hooks/useLazyMetadata.ts

@@ -0,0 +1,132 @@
+/**
+ * React hook for lazy metadata loading with loading states
+ */
+
+import { useState, useCallback } from "react";
+import type {
+	EntityMetadata,
+	AttributeMetadata,
+	RelationshipMetadata,
+} from "../../features/fetchxml/api/pptbClient";
+import * as metadataLoader from "../../features/fetchxml/api/dataverseMetadata";
+import { metadataCache } from "../../features/fetchxml/state/cache";
+
+interface UseLazyMetadataResult {
+	// Loaders
+	loadEntities: (advancedFindOnly?: boolean) => Promise<EntityMetadata[]>;
+	loadEntityMetadata: (logicalName: string) => Promise<EntityMetadata>;
+	loadAttributes: (logicalName: string) => Promise<AttributeMetadata[]>;
+	loadRelationships: (logicalName: string) => Promise<{
+		oneToMany: RelationshipMetadata[];
+		manyToOne: RelationshipMetadata[];
+		manyToMany: RelationshipMetadata[];
+	}>;
+
+	// State
+	isLoading: boolean;
+	error: Error | null;
+
+	// Utilities
+	clearCache: () => void;
+	clearEntityCache: (logicalName: string) => void;
+}
+
+export function useLazyMetadata(): UseLazyMetadataResult {
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState<Error | null>(null);
+
+	const loadEntities = useCallback(async (advancedFindOnly: boolean = true) => {
+		setIsLoading(true);
+		setError(null);
+		try {
+			// Check global cache first (preloaded by useAccessMode)
+			if (advancedFindOnly) {
+				const cached = metadataCache.getAllEntityMetadata();
+				if (cached) {
+					console.log(
+						"[useLazyMetadata] Using preloaded entity metadata:",
+						cached.length,
+						"entities"
+					);
+					return cached;
+				}
+			}
+
+			const entities = await metadataLoader.loadAllEntities(advancedFindOnly);
+			return entities;
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error("Failed to load entities");
+			setError(error);
+			throw error;
+		} finally {
+			setIsLoading(false);
+		}
+	}, []);
+
+	const loadEntityMetadata = useCallback(async (logicalName: string) => {
+		setIsLoading(true);
+		setError(null);
+		try {
+			const metadata = await metadataLoader.loadEntityMetadata(logicalName);
+			return metadata;
+		} catch (err) {
+			const error =
+				err instanceof Error ? err : new Error(`Failed to load metadata for ${logicalName}`);
+			setError(error);
+			throw error;
+		} finally {
+			setIsLoading(false);
+		}
+	}, []);
+
+	const loadAttributes = useCallback(async (logicalName: string) => {
+		setIsLoading(true);
+		setError(null);
+		try {
+			const attributes = await metadataLoader.loadEntityAttributes(logicalName);
+			return attributes;
+		} catch (err) {
+			const error =
+				err instanceof Error ? err : new Error(`Failed to load attributes for ${logicalName}`);
+			setError(error);
+			throw error;
+		} finally {
+			setIsLoading(false);
+		}
+	}, []);
+
+	const loadRelationships = useCallback(async (logicalName: string) => {
+		setIsLoading(true);
+		setError(null);
+		try {
+			const relationships = await metadataLoader.loadEntityRelationships(logicalName);
+			return relationships;
+		} catch (err) {
+			const error =
+				err instanceof Error ? err : new Error(`Failed to load relationships for ${logicalName}`);
+			setError(error);
+			throw error;
+		} finally {
+			setIsLoading(false);
+		}
+	}, []);
+
+	const clearCache = useCallback(() => {
+		metadataLoader.clearMetadataCache();
+	}, []);
+
+	const clearEntityCache = useCallback((logicalName: string) => {
+		metadataLoader.clearEntityCache(logicalName);
+	}, []);
+
+	return {
+		loadEntities,
+		loadEntityMetadata,
+		loadAttributes,
+		loadRelationships,
+		isLoading,
+		error,
+		clearCache,
+		clearEntityCache,
+	};
+}

package/src/shared/hooks/usePptbContext.ts

@@ -0,0 +1,170 @@
+/**
+ * Hook to access PPTB host context (connection, theme, etc.)
+ * Subscribes to PPTB events for dynamic updates
+ */
+
+import { useState, useEffect } from "react";
+
+export interface PptbContext {
+	theme: "light" | "dark";
+	connected: boolean;
+	environmentUrl?: string;
+	organizationId?: string;
+}
+
+// PPTB Event payload structure
+interface ToolBoxEventPayload {
+	event: string;
+	data: unknown;
+	timestamp?: string;
+}
+
+// Extend window interface for PPTB API
+declare global {
+	interface Window {
+		toolboxAPI?: {
+			utils?: {
+				getCurrentTheme?: () => Promise<"light" | "dark">;
+			};
+			connections?: {
+				getActiveConnection?: () => Promise<{
+					url?: string;
+					organizationId?: string;
+					name?: string;
+					environment?: string;
+				} | null>;
+			};
+			events?: {
+				// PPTB uses a single callback that receives all events
+				on?: (callback: (event: unknown, payload: ToolBoxEventPayload) => void) => void;
+				off?: (callback: (event: unknown, payload: ToolBoxEventPayload) => void) => void;
+				getHistory?: (count: number) => Promise<ToolBoxEventPayload[]>;
+			};
+		};
+	}
+}
+
+/**
+ * Get tool context from PPTB host
+ * Returns theme and connection status
+ * Subscribes to PPTB events for dynamic updates (theme, connection changes)
+ */
+export function usePptbContext(): PptbContext {
+	const [context, setContext] = useState<PptbContext>({
+		theme: "light", // Default to light theme
+		connected: false,
+	});
+
+	useEffect(() => {
+		console.log("🔄 usePptbContext: Initializing...");
+
+		// Check if running in PPTB host
+		if (typeof window === "undefined" || !window.toolboxAPI) {
+			console.log("💡 Running standalone - using default light theme");
+			return;
+		}
+
+		const toolboxAPI = window.toolboxAPI;
+
+		// ============ THEME ============
+		const updateTheme = async () => {
+			try {
+				const hostTheme = await toolboxAPI.utils?.getCurrentTheme?.();
+				console.log("🎨 getCurrentTheme() returned:", hostTheme);
+				const normalizedTheme =
+					hostTheme && String(hostTheme).toLowerCase() === "dark" ? "dark" : "light";
+				setContext((prev) => ({
+					...prev,
+					theme: normalizedTheme,
+				}));
+			} catch (err) {
+				console.warn("❌ Failed to get theme from host:", err);
+			}
+		};
+
+		// ============ CONNECTION ============
+		const updateConnection = async () => {
+			try {
+				const connection = await toolboxAPI.connections?.getActiveConnection?.();
+				console.log("🔗 getActiveConnection() returned:", connection);
+				setContext((prev) => ({
+					...prev,
+					connected: !!connection,
+					environmentUrl: connection?.url,
+					organizationId: connection?.organizationId,
+				}));
+			} catch (err) {
+				console.warn("❌ Failed to get active connection:", err);
+			}
+		};
+
+		// ============ EVENT HANDLER ============
+		// PPTB calls this with (event, payload) where payload has { event, data, timestamp }
+		const handlePptbEvent = (_event: unknown, payload: ToolBoxEventPayload) => {
+			console.log("🔔 PPTB Event received:", payload.event, payload.data);
+
+			switch (payload.event) {
+				case "settings:updated":
+					// Settings changed - check if theme was updated
+					if (payload.data && typeof payload.data === "object" && "theme" in payload.data) {
+						const themeValue = (payload.data as { theme: string }).theme;
+						console.log("🎨 Theme changed via settings:updated:", themeValue);
+						const normalizedTheme = String(themeValue).toLowerCase() === "dark" ? "dark" : "light";
+						setContext((prev) => ({
+							...prev,
+							theme: normalizedTheme,
+						}));
+					} else {
+						// Theme might have changed, refetch it
+						updateTheme();
+					}
+					break;
+
+				case "connection:updated":
+				case "connection:created":
+					// Connection changed - refetch connection info
+					console.log("🔗 Connection changed, refreshing...");
+					updateConnection();
+					break;
+
+				case "connection:deleted":
+					// Connection was deleted
+					console.log("🔗 Connection deleted");
+					setContext((prev) => ({
+						...prev,
+						connected: false,
+						environmentUrl: undefined,
+						organizationId: undefined,
+					}));
+					break;
+
+				default:
+					// Log other events for debugging
+					console.log("📢 Unhandled PPTB event:", payload.event);
+			}
+		};
+
+		// ============ INITIALIZATION ============
+		// Get initial theme and connection
+		updateTheme();
+		updateConnection();
+
+		// Subscribe to events
+		if (toolboxAPI.events?.on) {
+			console.log("✅ Subscribing to PPTB events...");
+			toolboxAPI.events.on(handlePptbEvent);
+		} else {
+			console.warn("⚠️ toolboxAPI.events.on not available");
+		}
+
+		// ============ CLEANUP ============
+		return () => {
+			if (toolboxAPI.events?.off) {
+				console.log("🧹 Unsubscribing from PPTB events...");
+				toolboxAPI.events.off(handlePptbEvent);
+			}
+		};
+	}, []);
+
+	return context;
+}