ui-soxo-bootstrap-core 2.4.25 → 2.5.0

package/core/modules/steps/steps.js

@@ -0,0 +1,332 @@
+/**
+ * ProcessStepsPage Component
+ *
+ * - Manages a multi-step, time-tracked process workflow.
+ * - Dynamically renders step-specific components based on configuration.
+ * - Tracks step and process durations with local persistence support.
+ * - Supports step navigation (next, previous, skip, timeline, keyboard).
+ * - Handles process submission and optional chaining to the next process.
+ * - Provides a collapsible timeline view and action controls.
+ */
+import React, { useEffect, useState } from 'react';
+import { Row, Col, Empty } from 'antd';
+import { Card } from './../../lib';
+import * as genericComponents from './../../lib';
+import moment from 'moment';
+import { Location } from './../../lib';
+import ActionButtons from './action-buttons';
+import { Dashboard } from '../../models';
+import './steps.scss';
+import TimelinePanel from './timeline';
+import { ExternalWindow } from '../../components';
+
+export default function ProcessStepsPage({ processId, match, CustomComponents = {}, ...props }) {
+  const allComponents = { ...genericComponents, ...CustomComponents };
+
+  const [loading, setLoading] = useState(false);
+  const [steps, setSteps] = useState([]);
+  const [activeStep, setActiveStep] = useState(0);
+  const [isStepCompleted, setIsStepCompleted] = useState(false);
+  const [currentProcessId, setCurrentProcessId] = useState(processId);
+  const [nextProcessId, setNextProcessId] = useState(null);
+  const [stepStartTime, setStepStartTime] = useState(null);
+  const [processStartTime, setProcessStartTime] = useState(null);
+  const [processTimings, setProcessTimings] = useState([]);
+  const [timelineCollapsed, setTimelineCollapsed] = useState(true);
+  const [showExternalWindow, setShowExternalWindow] = useState(false);
+  const urlParams = Location.search();
+
+  // Load process details based on the current process ID
+  useEffect(() => {
+    loadProcess(currentProcessId);
+
+    const saved = localStorage.getItem(`processTimings_${currentProcessId}`);
+    setProcessTimings(saved ? JSON.parse(saved) : []);
+
+    setProcessStartTime(Date.now());
+    setStepStartTime(Date.now());
+  }, [currentProcessId]);
+
+  //// Reset step start time whenever the active step changes
+
+  useEffect(() => {
+    setStepStartTime(Date.now());
+  }, [activeStep]);
+
+  // Check whether the current step is completed or mandatory
+  useEffect(() => {
+    if (steps.length > 0) {
+      setIsStepCompleted(steps[activeStep]?.is_mandatory !== true);
+    }
+  }, [activeStep, steps]);
+
+  // Save updated process timings to state and localStorage
+  const saveTimings = (updated) => {
+    setProcessTimings(updated);
+    localStorage.setItem(`processTimings_${currentProcessId}`, JSON.stringify(updated));
+  };
+  // Record time spent on the current step
+
+  const recordStepTime = (status = 'completed') => {
+    // Exit if step start time or step data is missing
+
+    if (!stepStartTime || !steps[activeStep]) return processTimings;
+    // Capture end time and calculate duration
+
+    const endTime = Date.now();
+    const duration = endTime - stepStartTime;
+    const stepId = steps[activeStep].step_id;
+    // Clone existing timings
+
+    const updated = [...processTimings];
+    const index = updated.findIndex((t) => t.step_id === stepId);
+    // Create timing entry for the step
+
+    const entry = {
+      step_id: stepId,
+      start_time: moment(stepStartTime).format('DD-MM-YYYY HH:mm:ss'),
+      end_time: moment(endTime).format('DD-MM-YYYY HH:mm:ss'),
+      duration,
+      status,
+    };
+    // Update existing entry or add a new one
+    if (index > -1) {
+      updated[index] = { ...updated[index], ...entry, duration: updated[index].duration + duration };
+    } else {
+      updated.push(entry);
+    }
+
+    return updated;
+  };
+
+  /**
+   * @param {*} processId
+   *
+   * Process Loading
+   * - Fetches process details and step configuration using the process ID.
+   * - Manages loading state during the API call.
+   * - Stores step data and prepares next process details if available.
+   * - Handles API errors and maintains UI stability.
+   */
+  async function loadProcess(processId) {
+    setLoading(true);
+    setNextProcessId(null);
+
+    try {
+      const result = await Dashboard.loadProcess(processId);
+
+      setSteps(result?.data?.steps || []);
+      if (result?.data?.next_process_id) setNextProcessId(result.data);
+    } catch (e) {
+      console.error('Error loading process steps:', e);
+    } finally {
+      setLoading(false);
+    }
+  }
+  /**
+   * @param {*} finalTimings
+   *
+   * Process Submission
+   * - Builds payload with process metadata, reference details, and step timings.
+   * - Submits process completion data to the backend.
+   * - Clears stored timings on successful submission.
+   * - Persists timing data locally if submission fails.
+   */
+  const handleProcessSubmit = async (finalTimings) => {
+    const payload = {
+      process_id: currentProcessId,
+      status: 'completed',
+      reference_id: urlParams?.opb_id || urlParams?.reference_id,
+      reference_number: urlParams?.opno || urlParams?.reference_number,
+      mode: urlParams?.mode,
+      process: {
+        process_start_time: moment(processStartTime).format('DD-MM-YYYY HH:mm'),
+        process_end_time: moment().format('DD-MM-YYYY HH:mm'),
+        steps: finalTimings,
+      },
+    };
+
+    try {
+      const response = await Dashboard.processLog(payload);
+
+      if (response.success) {
+        localStorage.removeItem(`processTimings_${currentProcessId}`);
+        setProcessTimings([]);
+        return true;
+      }
+    } catch (e) {
+      console.error('Error:', e);
+      saveTimings(finalTimings);
+    }
+    return false;
+  };
+  /**
+   * @param {number} index
+   * @param {string} status
+   *
+   * Step Navigation
+   * - Records time spent on the current step.
+   * - Saves updated step timing data.
+   * - Navigates to the specified step index.
+   */
+  const gotoStep = (index, status = 'completed') => {
+    const updated = recordStepTime(status);
+    saveTimings(updated);
+    setActiveStep(index);
+  };
+  /**
+   * Navigate to the next step
+   * - Records timing data and advances step index by one.
+   */
+  const handleNext = () => gotoStep(activeStep + 1);
+  /**
+   * Navigate to the previous step
+   * - Records timing data and moves to the previous step.
+   */
+  const handlePrevious = () => gotoStep(activeStep - 1);
+  /**
+   * Skip current step
+   * - Records timing with skipped status.
+   * - Moves to the next step.
+   */
+  const handleSkip = () => gotoStep(activeStep + 1, 'skipped');
+  /**
+   * Timeline Navigation
+   * - Navigates directly to the selected step.
+   * - Records timing data for the current step.
+   */
+  const handleTimelineClick = (i) => gotoStep(i);
+  /**
+   * Process Completion
+   * - Records final step timing.
+   * - Submits process completion data.
+   * - Navigates back on successful completion.
+   */
+  const handleFinish = async () => {
+    const final = recordStepTime();
+    if (await handleProcessSubmit(final)) props.history?.goBack();
+  };
+  /**
+   * Start Next Process
+   * - Records final timing of the current process.
+   * - Submits current process data.
+   * - Loads and initializes the next linked process.
+   */
+  const handleStartNextProcess = async () => {
+    const final = recordStepTime();
+    if (await handleProcessSubmit(final)) {
+      await loadProcess(nextProcessId.next_process_id);
+      setCurrentProcessId(nextProcessId.next_process_id);
+      setActiveStep(0);
+      setShowExternalWindow(true);
+    }
+  };
+  /**
+   * Dynamic Step Renderer
+   * - Resolves and renders step-specific components dynamically.
+   * - Passes configuration, parameters, and handlers to the component.
+   * - Handles missing steps or components gracefully.
+   */
+  const DynamicComponent = () => {
+    const step = steps[activeStep];
+    if (!step) return <Empty description="No step selected" />;
+
+    const Component = allComponents[step.related_page];
+    if (!Component) return <Empty description={`Component "${step.related_page}" not found`} />;
+
+    return <Component {...step.config} {...props} step={step} params={urlParams} onStepComplete={() => setIsStepCompleted(true)} />;
+  };
+  /**
+   * Keyboard Navigation
+   * - Enables left and right arrow keys for step navigation.
+   * - Prevents navigation beyond step boundaries.
+   * - Cleans up event listeners on unmount.
+   */
+  useEffect(() => {
+    const handleKeyDown = (event) => {
+      // Handle Left Arrow key press to go to the previous step
+      if (event.key === 'ArrowLeft') {
+        if (activeStep > 0) {
+          handlePrevious();
+        }
+      }
+      // Handle Right Arrow key press to go to the next step
+      else if (event.key === 'ArrowRight') {
+        if (activeStep < steps.length - 1) {
+          handleNext();
+        }
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [activeStep, steps, handlePrevious, handleNext]);
+
+  /**
+   * Renders the main process UI including timeline, step details,
+   * and action buttons. This content is reused in both normal view
+   * and external window view.
+   */
+  const renderContent = () => (
+    <Card>
+      <Row gutter={20}>
+        <Col xs={24} sm={24} lg={timelineCollapsed ? 2 : 6}>
+          <TimelinePanel
+            loading={loading}
+            steps={steps}
+            activeStep={activeStep}
+            timelineCollapsed={timelineCollapsed}
+            handleTimelineClick={handleTimelineClick}
+            setTimelineCollapsed={setTimelineCollapsed}
+          />
+        </Col>
+
+        <Col xs={24} sm={24} lg={timelineCollapsed ? 21 : 18}>
+          <div style={{ marginBottom: 20 }}>
+            <h2 style={{ margin: 0, fontSize: 16, fontWeight: 600 }}>{steps[activeStep]?.step_name}</h2>
+            <p style={{ margin: 0, color: '#666' }}>{steps[activeStep]?.step_description}</p>
+          </div>
+          <ActionButtons
+            loading={loading}
+            steps={steps}
+            activeStep={activeStep}
+            isStepCompleted={isStepCompleted}
+            renderDynamicComponent={DynamicComponent}
+            handlePrevious={handlePrevious}
+            handleNext={handleNext}
+            handleSkip={handleSkip}
+            handleFinish={handleFinish}
+            handleStartNextProcess={handleStartNextProcess}
+            nextProcessId={nextProcessId}
+            timelineCollapsed={timelineCollapsed}
+          />
+        </Col>
+      </Row>
+    </Card>
+  );
+  /**
+   * Renders content in both the main window and an external window
+   * when external window mode is enabled.
+   */
+  if (showExternalWindow && props.showExternalWindow) {
+    return (
+      <>
+        <ExternalWindow
+          title={steps[activeStep]?.step_name || 'Process Step'}
+          onClose={() => setShowExternalWindow(false)}
+          // left={window.screenX + window.outerWidth}
+          // top={window.screenY}
+          width={props.ExternalWindowWidth || 1000}
+          height={props.ExternalWindowHeight || 1000}
+        >
+          {renderContent()}
+        </ExternalWindow>
+        {renderContent()}
+      </>
+    );
+  }
+  /**
+   * Default render when external window mode is disabled.
+   */
+  return renderContent();
+}

package/core/modules/steps/steps.scss

@@ -0,0 +1,158 @@
+.timeline-card .ant-card-body {
+  padding: 20px;
+  min-height: 400px;
+  position: fixed; /* For positioning the arrow */
+}
+
+.timeline-sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  transition: all 0.3s ease;
+}
+
+.timeline-step {
+  display: flex;
+  cursor: pointer;
+}
+
+.timeline-step.active .step-number {
+  background: #3b82f6;
+  color: white;
+}
+
+.timeline-step.completed .step-number {
+  background:  #22c55e;
+  color: white;
+}
+
+.step-marker {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  margin-right: 14px;
+}
+
+.step-number {
+  width: 28px;
+  height: 28px;
+  border-radius: 50%;
+  background: #d9d9d9;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 600;
+}
+
+.vertical-line {
+  width: 2px;
+  height: 40px;
+  background: #d9d9d9;
+}
+
+.step-info {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+}
+
+.step-title {
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.step-main {
+  font-size: 15px;
+  font-weight: 600;
+}
+
+.toggle-arrow {
+  position: absolute;
+  top: 50%;
+  right: -12px; /* Position it just outside the card body padding */
+  transform: translateY(-50%);
+  width: 24px;
+  height: 24px;
+  background: #fff;
+  border: 1px solid #f0f0f0;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.09);
+  z-index: 10;
+  transition: all 0.3s ease;
+
+  &:hover {
+    background: #f5f5f5;
+  }
+}
+
+/* ============================
+   MOBILE & TABLET VIEW FIXES
+   ============================ */
+
+   
+
+@media (max-width: 992px) {   // iPad & tablets
+  .timeline-card .ant-card-body {
+    padding: 12px;
+    min-height: auto;
+  }
+
+  .timeline-sidebar {
+    flex-direction: row !important;
+    overflow-x: auto;
+    gap: 12px;
+    padding-bottom: 10px;
+    border-bottom: 1px solid #eee;
+  }
+
+  .timeline-step {
+    flex-direction: column;
+    align-items: center;
+  }
+
+  .step-marker {
+    margin-right: 0;
+  }
+
+  .step-info {
+    text-align: center;
+  }
+
+  .toggle-arrow {
+    display: none !important; /* Hide collapse icon */
+  }
+}
+
+@media (max-width: 768px) {   // mobile screens
+  .timeline-sidebar {
+    gap: 8px;
+  }
+
+  .step-number {
+    width: 24px;
+    height: 24px;
+    font-size: 12px;
+  }
+
+  .step-title {
+    font-size: 11px;
+  }
+
+  .step-main {
+    font-size: 13px;
+  }
+
+  .vertical-line {
+    display: none;
+  }
+
+  /* Card layout full width */
+  .timeline-card .ant-card-body {
+    padding: 10px;
+  }
+}
+

package/core/modules/steps/timeline.js

@@ -0,0 +1,54 @@
+/**
+ * TimelinePanel Component
+ *
+ * - Displays a vertical timeline for a multi-step process.
+ * - Highlights active and completed steps visually.
+ * - Allows direct navigation by clicking on timeline steps.
+ * - Supports collapsing and expanding the timeline view.
+ * - Shows a loading skeleton while step data is being fetched.
+ *
+ * Used as a visual step navigator within a step-based workflow.
+ */
+
+import React from 'react';
+import { Skeleton } from 'antd';
+import { LeftOutlined, RightOutlined } from '@ant-design/icons';
+import { Card } from '../../lib';
+
+export default function TimelinePanel({ loading, steps, activeStep, timelineCollapsed, handleTimelineClick, setTimelineCollapsed }) {
+  return (
+    <Card className="timeline-card">
+      {loading ? (
+        <Skeleton active />
+      ) : (
+        <div className={`timeline-sidebar ${timelineCollapsed ? 'collapsed' : ''}`}>
+          {steps.map((step, index) => (
+            <div
+              key={step.step_id}
+              className={`timeline-step 
+                ${index === activeStep ? 'active' : ''} 
+                ${index < activeStep ? 'completed' : ''}`}
+              onClick={() => handleTimelineClick(index)}
+            >
+              <div className="step-marker">
+                <div className="step-number">{index + 1}</div>
+                {index < steps.length - 1 && <div className="vertical-line"></div>}
+              </div>
+
+              {!timelineCollapsed && (
+                <div className="step-info">
+                  <div className="step-title">Step {index + 1}</div>
+                  <div className="step-main">{step.step_name}</div>
+                </div>
+              )}
+            </div>
+          ))}
+
+          <div className="toggle-arrow" onClick={() => setTimelineCollapsed(!timelineCollapsed)}>
+            {timelineCollapsed ? <RightOutlined /> : <LeftOutlined />}
+          </div>
+        </div>
+      )}
+    </Card>
+  );
+}

package/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  testEnvironment: 'jsdom',
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
+  transform: {
+    '^.+\\.js$': 'babel-jest',
+    '\\.(css|scss)$': 'jest-transform-stub',
+  },
+};

package/jest.setup.js

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ui-soxo-bootstrap-core",
-  "version": "2.4.25",
+  "version": "2.5.0",
   "description": "All the Core Components for you to start",
   "keywords": [
     "all in one"
@@ -13,7 +13,7 @@
   "main": "index.js",
   "scripts": {
     "size": "size-limit",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "jest",
     "start": "webpack-dev-server --mode development",
     "transpile": "babel / -d build --copy-files",
     "build": "webpack --mode production",
@@ -82,10 +82,13 @@
   "devDependencies": {
     "@babel/core": "^7.16.5",
     "@babel/plugin-proposal-class-properties": "^7.10.4",
-    "@babel/preset-env": "^7.10.4",
-    "@babel/preset-react": "^7.10.4",
+    "@babel/preset-env": "^7.28.5",
+    "@babel/preset-react": "^7.28.5",
     "@eslint/compat": "^1.1.1",
     "@eslint/js": "^9.9.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^12.1.5",
+    "babel-jest": "^27.5.1",
     "babel-loader": "^8.3.0",
     "babel-plugin-transform-class-properties": "^6.24.1",
     "babel-plugin-transform-object-rest-spread": "^6.26.0",
@@ -100,6 +103,8 @@
     "eslint-plugin-unicorn": "^55.0.0",
     "globals": "^15.9.0",
     "husky": "^9.1.5",
+    "jest": "^27.5.1",
+    "jest-transform-stub": "^2.0.0",
     "prettier": "^3.3.3",
     "sass-loader": "^10.5.2",
     "style-loader": "^1.3.0",