@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/src/page-templates/RelatedEntitiesPage.tsx

@@ -0,0 +1,578 @@
+import React, { useState, useEffect, useCallback } from 'react';
+import {
+  Stack,
+  Text,
+  Pivot,
+  PivotItem,
+  DetailsList,
+  IColumn,
+  SelectionMode,
+  CommandBar,
+  ICommandBarItemProps,
+  MessageBar,
+  MessageBarType,
+  Spinner,
+  SpinnerSize,
+  Panel,
+  PanelType,
+  SearchBox,
+  Breadcrumb,
+  IBreadcrumbItem,
+} from '@fluentui/react';
+import { BaseEntity } from '../models/BaseEntity';
+import { useDynamicsApi } from '../providers/DynamicsProvider';
+import { Logger } from '../components/Logging/logger';
+
+interface RelatedEntityConfig<T extends BaseEntity> {
+  key: string;
+  title: string;
+  entityLogicalName: string;
+  entityClass: any;
+  columns: IColumn[];
+  fetchXmlTemplate: string; // Should include {{parentId}} placeholder
+  relationshipField: string;
+  allowCreate?: boolean;
+  allowEdit?: boolean;
+  allowDelete?: boolean;
+  renderForm?: (
+    entity: T | null,
+    onSave: (entity: T) => void,
+    onCancel: () => void
+  ) => React.ReactNode;
+  customCommands?: ICommandBarItemProps[];
+}
+
+interface RelatedEntitiesPageProps<TParent extends BaseEntity> {
+  parentEntity: TParent;
+  parentTitle: string;
+  relatedEntityConfigs: RelatedEntityConfig<any>[];
+  onBack?: () => void;
+  breadcrumbItems?: IBreadcrumbItem[];
+  enableSearch?: boolean;
+}
+
+/**
+ * Generic related entities page template for Dynamics 365
+ * Displays master-detail relationships with tabbed navigation
+ */
+export function RelatedEntitiesPage<TParent extends BaseEntity>({
+  parentEntity,
+  parentTitle,
+  relatedEntityConfigs,
+  onBack,
+  breadcrumbItems = [],
+  enableSearch = true,
+}: RelatedEntitiesPageProps<TParent>) {
+  const { apiService } = useDynamicsApi();
+  const [selectedTab, setSelectedTab] = useState(
+    relatedEntityConfigs[0]?.key || ''
+  );
+  const [relatedData, setRelatedData] = useState<{ [key: string]: any[] }>({});
+  const [filteredData, setFilteredData] = useState<{ [key: string]: any[] }>(
+    {}
+  );
+  const [loading, setLoading] = useState<{ [key: string]: boolean }>({});
+  const [error, setError] = useState<string | null>(null);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [selectedItems, setSelectedItems] = useState<{ [key: string]: any }>(
+    {}
+  );
+  const [showPanel, setShowPanel] = useState(false);
+  const [panelConfig, setPanelConfig] =
+    useState<RelatedEntityConfig<any> | null>(null);
+  const [isEditing, setIsEditing] = useState(false);
+  const [refreshTriggers, setRefreshTriggers] = useState<{
+    [key: string]: number;
+  }>({});
+
+  // Load related entities for a specific tab
+  const loadRelatedEntities = useCallback(
+    async (config: RelatedEntityConfig<any>) => {
+      if (!apiService) {
+        setError('API service not available');
+        return;
+      }
+
+      try {
+        setLoading((prev) => ({ ...prev, [config.key]: true }));
+        setError(null);
+        Logger.log(`Loading ${config.title}...`);
+
+        const parentId =
+          (parentEntity as any).id ||
+          (parentEntity as any)[
+            Object.keys(parentEntity).find((key) => key.includes('id')) || ''
+          ];
+        const fetchXml = config.fetchXmlTemplate.replace(
+          '{{parentId}}',
+          parentId
+        );
+
+        const result = await apiService.retrieveMultipleRecords(
+          config.entityLogicalName,
+          fetchXml
+        );
+        const entities = (result.entities || []).map(
+          (data: any) => new config.entityClass(data)
+        );
+
+        setRelatedData((prev) => ({ ...prev, [config.key]: entities }));
+        setFilteredData((prev) => ({ ...prev, [config.key]: entities }));
+
+        Logger.log(`Loaded ${entities.length} ${config.title}`);
+      } catch (err) {
+        const errorMessage =
+          err instanceof Error ? err.message : `Failed to load ${config.title}`;
+        setError(errorMessage);
+        Logger.error(
+          `Error loading ${config.title}:`,
+          'RelatedEntitiesPage',
+          err
+        );
+      } finally {
+        setLoading((prev) => ({ ...prev, [config.key]: false }));
+      }
+    },
+    [apiService, parentEntity]
+  );
+
+  // Load data when tab changes or refresh triggers
+  useEffect(() => {
+    const config = relatedEntityConfigs.find((c) => c.key === selectedTab);
+    if (config) {
+      loadRelatedEntities(config);
+    }
+  }, [selectedTab, relatedEntityConfigs, loadRelatedEntities, refreshTriggers]);
+
+  // Handle search
+  useEffect(() => {
+    if (!enableSearch) return;
+
+    const newFilteredData = { ...relatedData };
+
+    if (searchQuery.trim()) {
+      for (const [key, entities] of Object.entries(relatedData)) {
+        newFilteredData[key] = entities.filter((entity) =>
+          Object.values(entity).some(
+            (value) =>
+              typeof value === 'string' &&
+              value.toLowerCase().includes(searchQuery.toLowerCase())
+          )
+        );
+      }
+    }
+
+    setFilteredData(newFilteredData);
+  }, [relatedData, searchQuery, enableSearch]);
+
+  // Handle item selection
+  const handleItemSelection = (config: RelatedEntityConfig<any>, item: any) => {
+    setSelectedItems((prev) => ({ ...prev, [config.key]: item }));
+  };
+
+  // Handle refresh
+  const handleRefresh = (configKey: string) => {
+    setRefreshTriggers((prev) => ({
+      ...prev,
+      [configKey]: (prev[configKey] || 0) + 1,
+    }));
+  };
+
+  // Handle new entity
+  const handleNew = (config: RelatedEntityConfig<any>) => {
+    setPanelConfig(config);
+    setSelectedItems((prev) => ({ ...prev, [config.key]: null }));
+    setIsEditing(false);
+    setShowPanel(true);
+  };
+
+  // Handle edit entity
+  const handleEdit = (config: RelatedEntityConfig<any>) => {
+    const selectedItem = selectedItems[config.key];
+    if (selectedItem) {
+      setPanelConfig(config);
+      setIsEditing(true);
+      setShowPanel(true);
+    }
+  };
+
+  // Handle delete entity
+  const handleDelete = async (config: RelatedEntityConfig<any>) => {
+    const selectedItem = selectedItems[config.key];
+    if (!selectedItem || !apiService) {
+      setError('Selected item or API service not available');
+      return;
+    }
+
+    try {
+      // Use the entity class static method or apiService directly
+      if (typeof selectedItem.delete === 'function') {
+        await selectedItem.delete(apiService);
+      } else {
+        // Fallback to direct API call
+        const entityId =
+          selectedItem.id || selectedItem[`${config.entityLogicalName}id`];
+        if (entityId) {
+          await apiService.deleteRecord(config.entityLogicalName, entityId);
+        } else {
+          throw new Error('Could not determine entity ID for deletion');
+        }
+      }
+
+      setSelectedItems((prev) => ({ ...prev, [config.key]: null }));
+      handleRefresh(config.key);
+      Logger.log(`${config.title} item deleted successfully`);
+    } catch (err) {
+      const errorMessage =
+        err instanceof Error
+          ? err.message
+          : `Failed to delete ${config.title} item`;
+      setError(errorMessage);
+      Logger.error(
+        `Error deleting ${config.title} item:`,
+        'RelatedEntitiesPage',
+        err
+      );
+    }
+  };
+
+  // Handle save
+  const handleSave = async (entity: any) => {
+    if (!panelConfig || !apiService) {
+      setError('Panel configuration or API service not available');
+      return;
+    }
+
+    try {
+      if (isEditing) {
+        // Update existing entity
+        if (typeof entity.update === 'function') {
+          await entity.update(apiService);
+        } else {
+          // Fallback to direct API call
+          const entityId =
+            entity.id || entity[`${panelConfig.entityLogicalName}id`];
+          if (entityId) {
+            const entityData = { ...entity };
+            delete entityData.id; // Remove id from update data
+            await apiService.updateRecord(
+              panelConfig.entityLogicalName,
+              entityId,
+              entityData
+            );
+          } else {
+            throw new Error('Could not determine entity ID for update');
+          }
+        }
+      } else {
+        // Create new entity
+        const parentId =
+          (parentEntity as any).id ||
+          (parentEntity as any)[
+            Object.keys(parentEntity).find((key) => key.includes('id')) || ''
+          ];
+        entity[panelConfig.relationshipField] = parentId;
+
+        if (typeof entity.constructor.create === 'function') {
+          await entity.constructor.create(apiService, entity);
+        } else {
+          // Fallback to direct API call
+          await apiService.createRecord(panelConfig.entityLogicalName, entity);
+        }
+      }
+
+      setShowPanel(false);
+      setPanelConfig(null);
+      setIsEditing(false);
+      handleRefresh(panelConfig.key);
+
+      Logger.log(`${panelConfig.title} saved successfully`);
+    } catch (err) {
+      const errorMessage =
+        err instanceof Error
+          ? err.message
+          : `Failed to save ${panelConfig.title}`;
+      setError(errorMessage);
+      Logger.error(
+        `Error saving ${panelConfig.title}:`,
+        'RelatedEntitiesPage',
+        err
+      );
+    }
+  };
+
+  // Handle panel dismiss
+  const handlePanelDismiss = () => {
+    setShowPanel(false);
+    setPanelConfig(null);
+    setIsEditing(false);
+  };
+
+  // Get current config and data
+  const currentConfig = relatedEntityConfigs.find((c) => c.key === selectedTab);
+  const currentData = filteredData[selectedTab] || [];
+  const currentSelectedItem = selectedItems[selectedTab];
+  const isCurrentLoading = loading[selectedTab] || false;
+
+  // Create command bar for current tab
+  const createCommandBar = (
+    config: RelatedEntityConfig<any>
+  ): ICommandBarItemProps[] => {
+    const items: ICommandBarItemProps[] = [
+      {
+        key: 'refresh',
+        text: 'Refresh',
+        iconProps: { iconName: 'Refresh' },
+        onClick: () => handleRefresh(config.key),
+      },
+    ];
+
+    if (config.allowCreate !== false) {
+      items.unshift({
+        key: 'new',
+        text: `New ${config.title}`,
+        iconProps: { iconName: 'Add' },
+        onClick: () => handleNew(config),
+      });
+    }
+
+    if (config.allowEdit !== false && currentSelectedItem) {
+      items.push({
+        key: 'edit',
+        text: 'Edit',
+        iconProps: { iconName: 'Edit' },
+        onClick: () => handleEdit(config),
+      });
+    }
+
+    if (config.allowDelete !== false && currentSelectedItem) {
+      items.push({
+        key: 'delete',
+        text: 'Delete',
+        iconProps: { iconName: 'Delete' },
+        onClick: () => {
+          handleDelete(config);
+        },
+      });
+    }
+
+    return [...items, ...(config.customCommands || [])];
+  };
+
+  // Enhanced columns with click handlers
+  const createEnhancedColumns = (
+    config: RelatedEntityConfig<any>
+  ): IColumn[] => {
+    return config.columns.map((column) => ({
+      ...column,
+      onRender:
+        column.onRender ||
+        ((item: any) => {
+          const value = item[column.fieldName || ''];
+          if (column.key === config.columns[0].key) {
+            // Make first column clickable
+            return (
+              <span
+                style={{ color: '#0078d4', cursor: 'pointer', fontWeight: 500 }}
+                onClick={() => handleItemSelection(config, item)}
+              >
+                {value || ''}
+              </span>
+            );
+          }
+          return <span>{value || ''}</span>;
+        }),
+    }));
+  };
+
+  // Default breadcrumb
+  const defaultBreadcrumbItems: IBreadcrumbItem[] = [
+    { text: parentTitle, key: 'parent', onClick: onBack },
+    { text: 'Related Records', key: 'related', isCurrentItem: true },
+  ];
+
+  const finalBreadcrumbItems =
+    breadcrumbItems.length > 0 ? breadcrumbItems : defaultBreadcrumbItems;
+
+  return (
+    <div style={{ padding: '20px', maxWidth: '100%' }}>
+      <Stack tokens={{ childrenGap: 20 }}>
+        {/* Breadcrumb */}
+        {onBack && <Breadcrumb items={finalBreadcrumbItems} />}
+
+        {/* Header */}
+        <Stack>
+          <Text variant="xxLarge" style={{ fontWeight: 600, color: '#323130' }}>
+            {(parentEntity as any).name || parentTitle} - Related Records
+          </Text>
+          <Text variant="medium" style={{ color: '#605e5c' }}>
+            Manage related entities and relationships
+          </Text>
+        </Stack>
+
+        {/* Error Message */}
+        {error && (
+          <MessageBar
+            messageBarType={MessageBarType.error}
+            onDismiss={() => setError(null)}
+          >
+            {error}
+          </MessageBar>
+        )}
+
+        {/* Search */}
+        {enableSearch && (
+          <SearchBox
+            placeholder="Search related records..."
+            value={searchQuery}
+            onChange={(_, newValue) => setSearchQuery(newValue || '')}
+            style={{ maxWidth: 400 }}
+          />
+        )}
+
+        {/* Tabs and Content */}
+        <Pivot
+          selectedKey={selectedTab}
+          onLinkClick={(item) => setSelectedTab(item?.props.itemKey || '')}
+        >
+          {relatedEntityConfigs.map((config) => (
+            <PivotItem
+              key={config.key}
+              headerText={`${config.title} (${(filteredData[config.key] || []).length})`}
+              itemKey={config.key}
+            >
+              <Stack tokens={{ childrenGap: 16 }} style={{ paddingTop: 20 }}>
+                {/* Command Bar */}
+                <CommandBar items={createCommandBar(config)} />
+
+                {/* Content */}
+                {isCurrentLoading ? (
+                  <div
+                    style={{
+                      display: 'flex',
+                      justifyContent: 'center',
+                      alignItems: 'center',
+                      minHeight: 200,
+                      flexDirection: 'column',
+                    }}
+                  >
+                    <Spinner
+                      size={SpinnerSize.large}
+                      label={`Loading ${config.title}...`}
+                    />
+                  </div>
+                ) : currentData.length === 0 ? (
+                  <div
+                    style={{
+                      textAlign: 'center',
+                      padding: '40px 20px',
+                      color: '#605e5c',
+                      border: '1px solid #edebe9',
+                      borderRadius: 4,
+                    }}
+                  >
+                    <div
+                      style={{
+                        fontSize: 48,
+                        marginBottom: 16,
+                        color: '#a19f9d',
+                      }}
+                    >
+                      📋
+                    </div>
+                    <Text
+                      variant="large"
+                      style={{
+                        fontWeight: 600,
+                        marginBottom: 8,
+                        color: '#323130',
+                      }}
+                    >
+                      {searchQuery
+                        ? 'No matching records found'
+                        : `No ${config.title} found`}
+                    </Text>
+                    <Text variant="medium">
+                      {searchQuery
+                        ? 'Try adjusting your search criteria'
+                        : config.allowCreate !== false
+                          ? `Click "New ${config.title}" to get started`
+                          : 'No records available'}
+                    </Text>
+                  </div>
+                ) : (
+                  <DetailsList
+                    items={currentData}
+                    columns={createEnhancedColumns(config)}
+                    setKey={config.key}
+                    layoutMode={0}
+                    selectionMode={SelectionMode.single}
+                    onActiveItemChanged={(item) =>
+                      handleItemSelection(config, item)
+                    }
+                    isHeaderVisible={true}
+                  />
+                )}
+              </Stack>
+            </PivotItem>
+          ))}
+        </Pivot>
+
+        {/* Form Panel */}
+        {panelConfig && (
+          <Panel
+            headerText={
+              isEditing
+                ? `Edit ${panelConfig.title}`
+                : `New ${panelConfig.title}`
+            }
+            isOpen={showPanel}
+            onDismiss={handlePanelDismiss}
+            type={PanelType.medium}
+            closeButtonAriaLabel="Close"
+          >
+            <div style={{ paddingTop: 20 }}>
+              {panelConfig.renderForm ? (
+                panelConfig.renderForm(
+                  isEditing ? selectedItems[panelConfig.key] : null,
+                  handleSave,
+                  handlePanelDismiss
+                )
+              ) : (
+                <div
+                  style={{ padding: 20, textAlign: 'center', color: '#605e5c' }}
+                >
+                  <Text>Form not configured for {panelConfig.title}</Text>
+                </div>
+              )}
+            </div>
+          </Panel>
+        )}
+      </Stack>
+    </div>
+  );
+}
+
+// Helper function to create related entity FetchXML
+export function createRelatedEntityFetchXml(
+  entityName: string,
+  attributes: string[],
+  relationshipField: string,
+  orderBy?: string
+): string {
+  const attributeElements = attributes
+    .map((attr) => `<attribute name="${attr}" />`)
+    .join('\n            ');
+  const orderElement = orderBy ? `<order attribute="${orderBy}" />` : '';
+
+  return `
+    <fetch>
+      <entity name="${entityName}">
+        ${attributeElements}
+        ${orderElement}
+        <filter>
+          <condition attribute="${relationshipField}" operator="eq" value="{{parentId}}" />
+        </filter>
+      </entity>
+    </fetch>`;
+}