@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/src/examples/component-examples/opportunity-management.tsx

@@ -0,0 +1,625 @@
+/**
+ * Example: Creating a custom management component
+ *
+ * This example demonstrates how to create a management component
+ * for a custom entity following the established patterns from
+ * AccountManagement and ContactManagement.
+ *
+ * @example
+ * ```typescript
+ * // Usage in your application
+ * import { OpportunityManagement } from './examples/component-examples/opportunity-management';
+ *
+ * function App() {
+ *   return (
+ *     <DynamicsProvider>
+ *       <OpportunityManagement />
+ *     </DynamicsProvider>
+ *   );
+ * }
+ * ```
+ */
+
+import React, { useState, useEffect, useCallback } from 'react';
+import {
+  Button,
+  TextField,
+  DetailsList,
+  Dialog,
+  Panel,
+  Dropdown,
+  DynamicsColumn,
+} from '@khester/dynamics-ui-components';
+import {
+  SelectionMode,
+  DetailsListLayoutMode,
+  CheckboxVisibility,
+} from '@fluentui/react';
+import { useDynamicsApi } from '../../providers/DynamicsProvider';
+import { Logger } from '../../components/Logging/logger';
+import {
+  Opportunity,
+  OpportunityConstants,
+  SalesStageCode_OptionSet,
+} from '../entity-examples/opportunity-model';
+
+/**
+ * Opportunity Management Component Props
+ */
+interface OpportunityManagementProps {
+  /** Optional account ID to filter opportunities */
+  accountId?: string;
+  /** Whether to show the create button */
+  showCreateButton?: boolean;
+  /** Custom title for the component */
+  title?: string;
+}
+
+/**
+ * Column configuration for the opportunities list
+ * Following the same pattern as AccountManagement and ContactManagement
+ */
+const columns: DynamicsColumn[] = [
+  {
+    key: OpportunityConstants.PrimaryName,
+    name: 'Opportunity Name',
+    fieldName: OpportunityConstants.PrimaryName,
+    minWidth: 200,
+    maxWidth: 300,
+    isResizable: true,
+  },
+  {
+    key: OpportunityConstants.EstimatedValue,
+    name: 'Est. Value',
+    fieldName: OpportunityConstants.EstimatedValue,
+    minWidth: 120,
+    maxWidth: 150,
+    isResizable: true,
+    onRender: (item: Opportunity) => {
+      return item.estimatedvalue
+        ? `$${item.estimatedvalue.toLocaleString()}`
+        : '';
+    },
+  },
+  {
+    key: OpportunityConstants.CloseProbability,
+    name: 'Close %',
+    fieldName: OpportunityConstants.CloseProbability,
+    minWidth: 80,
+    maxWidth: 100,
+    isResizable: true,
+    onRender: (item: Opportunity) => {
+      return item.closeprobability ? `${item.closeprobability}%` : '';
+    },
+  },
+  {
+    key: OpportunityConstants.EstimatedCloseDate,
+    name: 'Close Date',
+    fieldName: OpportunityConstants.EstimatedCloseDate,
+    minWidth: 120,
+    maxWidth: 150,
+    isResizable: true,
+    onRender: (item: Opportunity) => {
+      return item.estimatedclosedate
+        ? new Date(item.estimatedclosedate).toLocaleDateString()
+        : '';
+    },
+  },
+  {
+    key: OpportunityConstants.SalesStageCode,
+    name: 'Stage',
+    fieldName: OpportunityConstants.SalesStageCode,
+    minWidth: 100,
+    maxWidth: 120,
+    isResizable: true,
+    onRender: (item: Opportunity) => {
+      const stageMap: Record<number, string> = {
+        [SalesStageCode_OptionSet.Qualify]: 'Qualify',
+        [SalesStageCode_OptionSet.Develop]: 'Develop',
+        [SalesStageCode_OptionSet.Propose]: 'Propose',
+        [SalesStageCode_OptionSet.Close]: 'Close',
+      };
+      return item.salesstagecode !== undefined
+        ? stageMap[item.salesstagecode] || 'Unknown'
+        : '';
+    },
+  },
+  {
+    key: OpportunityConstants.CreatedOn,
+    name: 'Created',
+    fieldName: OpportunityConstants.CreatedOn,
+    minWidth: 120,
+    maxWidth: 150,
+    isResizable: true,
+  },
+];
+
+/**
+ * Sales stage filter options
+ */
+const salesStageOptions = [
+  { key: 'all', text: 'All Stages' },
+  { key: SalesStageCode_OptionSet.Qualify, text: 'Qualify' },
+  { key: SalesStageCode_OptionSet.Develop, text: 'Develop' },
+  { key: SalesStageCode_OptionSet.Propose, text: 'Propose' },
+  { key: SalesStageCode_OptionSet.Close, text: 'Close' },
+];
+
+/**
+ * OpportunityManagement Component
+ *
+ * Provides complete CRUD interface for opportunities with:
+ * - List view with sorting and filtering
+ * - Search functionality
+ * - Create, edit, and delete operations
+ * - Sales stage filtering
+ * - Integration with logging system
+ *
+ * @param props - Component properties
+ * @returns JSX.Element
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * <OpportunityManagement />
+ *
+ * // With account filter
+ * <OpportunityManagement
+ *   accountId="account-guid-here"
+ *   title="Account Opportunities"
+ * />
+ *
+ * // Read-only view
+ * <OpportunityManagement
+ *   showCreateButton={false}
+ * />
+ * ```
+ */
+export const OpportunityManagement: React.FC<OpportunityManagementProps> = ({
+  accountId,
+  showCreateButton = true,
+  title = 'Opportunity Management',
+}) => {
+  const { apiService, isEnvironmentMock, environmentType } = useDynamicsApi();
+
+  // State management
+  const [opportunities, setOpportunities] = useState<Opportunity[]>([]);
+  const [filteredOpportunities, setFilteredOpportunities] = useState<
+    Opportunity[]
+  >([]);
+  const [loading, setLoading] = useState(false);
+  const [searchText, setSearchText] = useState('');
+  const [selectedOpportunity, setSelectedOpportunity] =
+    useState<Opportunity | null>(null);
+  const [salesStageFilter, setSalesStageFilter] = useState<string>('all');
+
+  // Panel and dialog state
+  const [showNewOpportunityPanel, setShowNewOpportunityPanel] = useState(false);
+  const [showEditOpportunityPanel, setShowEditOpportunityPanel] =
+    useState(false);
+  const [showDeleteDialog, setShowDeleteDialog] = useState(false);
+  const [opportunityToDelete, setOpportunityToDelete] =
+    useState<Opportunity | null>(null);
+
+  /**
+   * Log component initialization
+   */
+  useEffect(() => {
+    Logger.userAction(
+      'OpportunityManagement loaded',
+      { environmentType, isEnvironmentMock, accountId },
+      'OpportunityManagement'
+    );
+  }, [environmentType, isEnvironmentMock, accountId]);
+
+  /**
+   * Load opportunities from the API
+   * Handles both general and account-specific loading
+   */
+  const loadOpportunities = useCallback(async () => {
+    if (!apiService) {
+      Logger.error(
+        'API service not available',
+        'OpportunityManagement.loadOpportunities'
+      );
+      return;
+    }
+
+    setLoading(true);
+    Logger.log(
+      'Loading opportunities',
+      'OpportunityManagement.loadOpportunities'
+    );
+
+    try {
+      let opportunitiesData: Opportunity[];
+
+      if (accountId) {
+        // Load opportunities for specific account
+        opportunitiesData = await Opportunity.retrieveByAccount(
+          apiService,
+          accountId
+        );
+      } else {
+        // Load all active opportunities
+        opportunitiesData =
+          await Opportunity.retrieveActiveOpportunities(apiService);
+      }
+
+      // Process opportunities for display
+      const opportunitiesWithDisplayData = opportunitiesData.map(
+        (opportunity) => {
+          const opportunityInstance = new Opportunity(opportunity);
+          return {
+            ...opportunityInstance,
+            createdon: opportunity.createdon
+              ? new Date(opportunity.createdon).toLocaleDateString()
+              : '',
+          } as Opportunity;
+        }
+      );
+
+      setOpportunities(opportunitiesWithDisplayData);
+      setFilteredOpportunities(opportunitiesWithDisplayData);
+
+      Logger.log(
+        `Successfully loaded ${opportunitiesWithDisplayData.length} opportunities`,
+        'OpportunityManagement.loadOpportunities'
+      );
+    } catch (error) {
+      Logger.error(
+        'Failed to load opportunities',
+        'OpportunityManagement.loadOpportunities',
+        error
+      );
+    } finally {
+      setLoading(false);
+    }
+  }, [apiService, accountId]);
+
+  /**
+   * Initial data load
+   */
+  useEffect(() => {
+    loadOpportunities();
+  }, [loadOpportunities]);
+
+  /**
+   * Filter opportunities based on search text and sales stage
+   */
+  useEffect(() => {
+    let filtered = opportunities;
+
+    // Apply search filter
+    if (searchText) {
+      filtered = filtered.filter(
+        (opportunity) =>
+          opportunity.name?.toLowerCase().includes(searchText.toLowerCase()) ||
+          opportunity.description
+            ?.toLowerCase()
+            .includes(searchText.toLowerCase())
+      );
+    }
+
+    // Apply sales stage filter
+    if (salesStageFilter !== 'all') {
+      const stageValue = parseInt(salesStageFilter);
+      filtered = filtered.filter(
+        (opportunity) => opportunity.salesstagecode === stageValue
+      );
+    }
+
+    setFilteredOpportunities(filtered);
+  }, [opportunities, searchText, salesStageFilter]);
+
+  /**
+   * Handle opportunity item selection/invocation
+   */
+  const handleItemInvoked = useCallback(
+    (item: Opportunity) => {
+      Logger.userAction(
+        'Opportunity item invoked',
+        { opportunityId: item.opportunityid, opportunityName: item.name },
+        'OpportunityManagement.handleItemInvoked'
+      );
+
+      if (selectedOpportunity?.opportunityid === item.opportunityid) {
+        setShowEditOpportunityPanel(true);
+      } else {
+        setSelectedOpportunity(item);
+      }
+    },
+    [selectedOpportunity]
+  );
+
+  /**
+   * Handle new opportunity creation
+   */
+  const handleNewOpportunity = useCallback(() => {
+    Logger.userAction(
+      'New opportunity panel opened',
+      {},
+      'OpportunityManagement.handleNewOpportunity'
+    );
+    setShowNewOpportunityPanel(true);
+  }, []);
+
+  /**
+   * Handle opportunity editing
+   */
+  const handleEditOpportunity = useCallback(() => {
+    if (selectedOpportunity) {
+      Logger.userAction(
+        'Edit opportunity panel opened',
+        {
+          opportunityId: selectedOpportunity.opportunityid,
+          opportunityName: selectedOpportunity.name,
+        },
+        'OpportunityManagement.handleEditOpportunity'
+      );
+      setShowEditOpportunityPanel(true);
+    }
+  }, [selectedOpportunity]);
+
+  /**
+   * Handle opportunity deletion
+   */
+  const handleDeleteOpportunity = useCallback(() => {
+    if (selectedOpportunity) {
+      Logger.userAction(
+        'Delete opportunity dialog opened',
+        {
+          opportunityId: selectedOpportunity.opportunityid,
+          opportunityName: selectedOpportunity.name,
+        },
+        'OpportunityManagement.handleDeleteOpportunity'
+      );
+      setOpportunityToDelete(selectedOpportunity);
+      setShowDeleteDialog(true);
+    }
+  }, [selectedOpportunity]);
+
+  /**
+   * Confirm opportunity deletion
+   */
+  const confirmDelete = useCallback(async () => {
+    if (opportunityToDelete && apiService) {
+      try {
+        Logger.userAction(
+          'Opportunity deletion confirmed',
+          {
+            opportunityId: opportunityToDelete.opportunityid,
+            opportunityName: opportunityToDelete.name,
+          },
+          'OpportunityManagement.confirmDelete'
+        );
+
+        await Opportunity.delete(
+          apiService,
+          opportunityToDelete.opportunityid!
+        );
+        await loadOpportunities();
+
+        setShowDeleteDialog(false);
+        setOpportunityToDelete(null);
+        setSelectedOpportunity(null);
+
+        Logger.log(
+          `Successfully deleted opportunity: ${opportunityToDelete.name}`,
+          'OpportunityManagement.confirmDelete'
+        );
+      } catch (error) {
+        Logger.error(
+          `Failed to delete opportunity: ${opportunityToDelete.name}`,
+          'OpportunityManagement.confirmDelete',
+          error
+        );
+      }
+    }
+  }, [opportunityToDelete, apiService, loadOpportunities]);
+
+  /**
+   * Handle opportunity save (create or update)
+   */
+  const handleOpportunitySaved = useCallback(() => {
+    Logger.userAction(
+      'Opportunity saved, refreshing list',
+      {},
+      'OpportunityManagement.handleOpportunitySaved'
+    );
+    loadOpportunities();
+    setShowNewOpportunityPanel(false);
+    setShowEditOpportunityPanel(false);
+    setSelectedOpportunity(null);
+  }, [loadOpportunities]);
+
+  /**
+   * Handle sales stage filter change
+   */
+  const handleSalesStageFilterChange = useCallback(
+    (
+      _event: React.FormEvent<HTMLDivElement>,
+      option?: { key: string | number | undefined; text: string }
+    ) => {
+      if (option) {
+        const newStage = option.key?.toString() || 'all';
+        Logger.userAction(
+          'Sales stage filter changed',
+          { from: salesStageFilter, to: newStage },
+          'OpportunityManagement.handleSalesStageFilterChange'
+        );
+        setSalesStageFilter(newStage);
+      }
+    },
+    [salesStageFilter]
+  );
+
+  return (
+    <div className="opportunity-management">
+      <div className="opportunity-management__header">
+        <h2>{title}</h2>
+        <div className="opportunity-management__actions">
+          <TextField
+            placeholder="Search opportunities..."
+            value={searchText}
+            onChange={(_, value) => setSearchText(value || '')}
+            iconProps={{ iconName: 'Search' }}
+          />
+          <Dropdown
+            placeholder="Filter by stage"
+            options={salesStageOptions}
+            selectedKey={salesStageFilter}
+            onChange={handleSalesStageFilterChange}
+          />
+          {showCreateButton && (
+            <Button
+              text="New Opportunity"
+              variant="primary"
+              onClick={handleNewOpportunity}
+              iconProps={{ iconName: 'Add' }}
+            />
+          )}
+        </div>
+      </div>
+
+      <div className="opportunity-management__toolbar">
+        <Button
+          text="Edit"
+          onClick={handleEditOpportunity}
+          disabled={!selectedOpportunity}
+          iconProps={{ iconName: 'Edit' }}
+        />
+        <Button
+          text="Delete"
+          onClick={handleDeleteOpportunity}
+          disabled={!selectedOpportunity}
+          iconProps={{ iconName: 'Delete' }}
+        />
+        <Button
+          text="Refresh"
+          onClick={loadOpportunities}
+          iconProps={{ iconName: 'Refresh' }}
+        />
+      </div>
+
+      <div className="opportunity-management__list">
+        <DetailsList
+          items={filteredOpportunities}
+          columns={columns}
+          onItemInvoked={handleItemInvoked}
+          selectionMode={SelectionMode.single}
+          layoutMode={DetailsListLayoutMode.justified}
+          checkboxVisibility={CheckboxVisibility.onHover}
+        />
+
+        {loading && (
+          <div className="opportunity-management__loading">
+            Loading opportunities...
+          </div>
+        )}
+
+        {!loading && filteredOpportunities.length === 0 && (
+          <div className="opportunity-management__empty">
+            {searchText || salesStageFilter !== 'all'
+              ? 'No opportunities found matching your filters.'
+              : accountId
+                ? 'No opportunities found for this account. Create your first opportunity!'
+                : 'No opportunities found. Create your first opportunity!'}
+          </div>
+        )}
+      </div>
+
+      {/* Delete Confirmation Dialog */}
+      <Dialog
+        hidden={!showDeleteDialog}
+        onDismiss={() => setShowDeleteDialog(false)}
+        title="Confirm Delete"
+        content={`Are you sure you want to delete "${opportunityToDelete?.name}"? This action cannot be undone.`}
+        actions={[
+          { text: 'Delete', onClick: confirmDelete, primary: true },
+          { text: 'Cancel', onClick: () => setShowDeleteDialog(false) },
+        ]}
+      />
+
+      {/* Note: OpportunityForm would need to be created following the AccountForm/ContactForm pattern */}
+      {/* This example focuses on the management component structure */}
+    </div>
+  );
+};
+
+/**
+ * CSS classes for styling (would be in a separate .css file)
+ */
+export const opportunityManagementStyles = `
+.opportunity-management {
+  padding: 16px;
+}
+
+.opportunity-management__header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 16px;
+  flex-wrap: wrap;
+  gap: 16px;
+}
+
+.opportunity-management__header h2 {
+  margin: 0;
+  font-size: 20px;
+  font-weight: 600;
+  color: #323130;
+}
+
+.opportunity-management__actions {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+.opportunity-management__toolbar {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 16px;
+  padding: 8px 0;
+  border-bottom: 1px solid #edebe9;
+}
+
+.opportunity-management__list {
+  min-height: 400px;
+  border: 1px solid #edebe9;
+  border-radius: 4px;
+}
+
+.opportunity-management__loading,
+.opportunity-management__empty {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  height: 200px;
+  color: #605e5c;
+  font-style: italic;
+  text-align: center;
+  padding: 16px;
+}
+
+@media (max-width: 768px) {
+  .opportunity-management {
+    padding: 8px;
+  }
+  
+  .opportunity-management__header {
+    flex-direction: column;
+    align-items: stretch;
+  }
+  
+  .opportunity-management__actions {
+    justify-content: stretch;
+  }
+  
+  .opportunity-management__toolbar {
+    flex-wrap: wrap;
+  }
+}
+`;