dce-reactkit 5.0.0 → 5.0.2

package/src/components/FakeProgressBar.tsx

@@ -0,0 +1,274 @@
+/**
+ * Fake progress bar that approaches completion but never fully finishes.
+ * Built on top of the existing ProgressBar component.
+ *
+ * Two phases:
+ *   1. Fast phase (0–90%): random jumps of 1–5% at randomized intervals,
+ *      paced to reach ~90% in roughly estimatedTimeSec seconds.
+ *   2. Slow phase (90–99%): crawls 1% at a time with longer random delays,
+ *      never reaching 100% on its own.
+ *
+ * When isFinished becomes true, the bar immediately jumps to 100%.
+ * @author Yuen Ler Chow
+ */
+
+// Import React
+import React, { useReducer, useEffect } from 'react';
+
+// Import helpers
+import { waitMs } from 'dce-commonkit';
+
+// Import types
+import Variant from '../types/Variant';
+import ProgressBarSize from '../types/ProgressBarSize';
+
+// Import components
+import ProgressBar from './ProgressBar';
+
+/*------------------------------------------------------------------------*/
+/* ------------------------------ Constants ----------------------------- */
+/*------------------------------------------------------------------------*/
+
+// Percent where the bar switches from fast random jumps to a slow crawl
+const SLOW_PHASE_START_PERCENT = 90;
+
+// Highest percent the bar will reach on its own (before isFinished is true)
+const MAX_UNFINISHED_PERCENT = 99;
+
+// Average step size during the fast phase (uniform random from 1–5)
+const AVG_FAST_PHASE_STEP = 3;
+
+// Minimum delay (ms) between steps during the slow phase
+const SLOW_PHASE_MIN_DELAY_MS = 2000;
+
+// Maximum delay (ms) between steps during the slow phase
+const SLOW_PHASE_MAX_DELAY_MS = 5000;
+
+/*------------------------------------------------------------------------*/
+/* -------------------------------- Types ------------------------------- */
+/*------------------------------------------------------------------------*/
+
+// Props definition
+type Props = {
+  // True if the task is finished (triggers animation to 100%)
+  isFinished?: boolean,
+  // Estimated time (in seconds) to finish the task (default 8)
+  estimatedTimeSec?: number,
+  // Whether to show striped effect (default false)
+  striped?: boolean,
+  // Variant of the progress bar (default warning)
+  variant?: Variant,
+  // Background variants (default secondary subtle)
+  bgVariant?: Variant,
+  // Hide outline (default false)
+  showOutline?: boolean,
+  // Size of the progress bar (default md)
+  size?: ProgressBarSize,
+};
+
+/*------------------------------------------------------------------------*/
+/* -------------------------------- State ------------------------------- */
+/*------------------------------------------------------------------------*/
+
+/* -------- State Definition -------- */
+
+type State = {
+  // Current progress percentage (0-99)
+  progress: number,
+};
+
+/* ------------- Actions ------------ */
+
+// Types of actions
+enum ActionType {
+  // Advance the progress by a given step
+  Advance = 'Advance',
+  // Set progress to 100% (task complete)
+  Complete = 'Complete',
+}
+
+// Action definitions
+type Action = (
+  | {
+    // Action type
+    type: ActionType.Advance,
+    // Number of percent points to advance
+    step: number,
+  }
+  | {
+    // Action type
+    type: ActionType.Complete,
+  }
+);
+
+/**
+ * Reducer that executes actions
+ * @author Yuen Ler Chow
+ * @param state current state
+ * @param action action to execute
+ */
+const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case ActionType.Advance: {
+      return {
+        ...state,
+        progress: Math.min(100, state.progress + action.step),
+      };
+    }
+    case ActionType.Complete: {
+      return {
+        ...state,
+        progress: 100,
+      };
+    }
+    default: {
+      return state;
+    }
+  }
+};
+
+/*------------------------------------------------------------------------*/
+/* ------------------------------ Component ----------------------------- */
+/*------------------------------------------------------------------------*/
+
+const FakeProgressBar: React.FC<Props> = (props) => {
+  /*------------------------------------------------------------------------*/
+  /* -------------------------------- Setup ------------------------------- */
+  /*------------------------------------------------------------------------*/
+
+  /* -------------- Props ------------- */
+
+  // Destructure props
+  const {
+    isFinished,
+    estimatedTimeSec = 8,
+    striped,
+    variant,
+    bgVariant,
+    showOutline,
+    size,
+  } = props;
+
+  /* -------------- State ------------- */
+
+  // Initial state
+  const initialState: State = {
+    progress: 0,
+  };
+
+  // Initialize state
+  const [state, dispatch] = useReducer(reducer, initialState);
+
+  // Destructure common state
+  const {
+    progress,
+  } = state;
+
+  // Convert estimate to milliseconds
+  const estimatedMs = estimatedTimeSec * 1000;
+
+  // Average interval between updates to reach ~90% in the estimated time
+  const avgIntervalMs = (estimatedMs / SLOW_PHASE_START_PERCENT) * AVG_FAST_PHASE_STEP;
+
+  /*------------------------------------------------------------------------*/
+  /* ------------------------- Lifecycle Functions ------------------------ */
+  /*------------------------------------------------------------------------*/
+
+  /**
+   * Animate to 100% when isFinished becomes true
+   * @author Yuen Ler Chow
+   */
+  useEffect(
+    () => {
+      if (isFinished) {
+        dispatch({
+          type: ActionType.Complete,
+        });
+      }
+    },
+    [isFinished],
+  );
+
+  /**
+   * Advance the progress in two phases:
+   * 1) Random jumps up to 90%
+   * 2) Slow crawl from 90% to 99%
+   * @author Yuen Ler Chow
+   */
+  useEffect(
+    () => {
+      // Stop if already finished or at max
+      if (isFinished || progress >= MAX_UNFINISHED_PERCENT) {
+        return;
+      }
+
+      // Determine which phase we are in
+      const inFastPhase = progress < SLOW_PHASE_START_PERCENT;
+
+      // Default values
+      let delay = avgIntervalMs;
+      let step = 1;
+
+      if (inFastPhase) {
+        // Randomize delay around the average interval for variability
+        const randomnessMultiplier = 0.5 + (Math.random());
+        delay = avgIntervalMs * randomnessMultiplier;
+
+        // Randomly move forward by 1-5%, capped at 90%
+        step = Math.min(
+          1 + Math.floor(Math.random() * 5),
+          SLOW_PHASE_START_PERCENT - progress,
+        );
+      } else {
+        // Crawl slowly 1% at a time, clamped so we don't exceed 99%
+        delay = SLOW_PHASE_MIN_DELAY_MS + (Math.random() * (SLOW_PHASE_MAX_DELAY_MS - SLOW_PHASE_MIN_DELAY_MS));
+        step = Math.min(1, MAX_UNFINISHED_PERCENT - progress);
+      }
+
+      // Track whether this effect invocation is still current
+      let cancelled = false;
+
+      // Wait then dispatch the next progress update
+      (async () => {
+        await waitMs(delay);
+        if (!cancelled) {
+          dispatch({
+            type: ActionType.Advance,
+            step,
+          });
+        }
+      })();
+
+      return () => {
+        cancelled = true;
+      };
+    },
+    [progress, avgIntervalMs, isFinished],
+  );
+
+  /*------------------------------------------------------------------------*/
+  /* ------------------------------- Render ------------------------------- */
+  /*------------------------------------------------------------------------*/
+
+  /*----------------------------------------*/
+  /* --------------- Main UI -------------- */
+  /*----------------------------------------*/
+
+  return (
+    <ProgressBar
+      percentProgress={progress}
+      striped={striped}
+      variant={variant}
+      bgVariant={bgVariant}
+      showOutline={showOutline}
+      size={size}
+    />
+  );
+};
+
+/*------------------------------------------------------------------------*/
+/* ------------------------------- Wrap Up ------------------------------ */
+/*------------------------------------------------------------------------*/
+
+// Export component
+export default FakeProgressBar;

package/src/components/ProgressBar.tsx

@@ -10,6 +10,12 @@ import React from 'react';
 import Variant from '../types/Variant';
 import ProgressBarSize from '../types/ProgressBarSize';
 
+// Import helpers
+import {
+  roundToNumDecimals,
+  padDecimalZeros,
+} from 'dce-commonkit';
+
 /*------------------------------------------------------------------------*/
 /* -------------------------------- Types ------------------------------- */
 /*------------------------------------------------------------------------*/
@@ -75,7 +81,7 @@ type ProgressStatus = (
 const ITEM_WIDTH_MULTIPLIER = 1.3;
 
 // Constant for percent width
-const PERCENT_WIDTH = 3;
+const PERCENT_WIDTH = 2.7;
 
 // Constant for item width
 const ITEM_WIDTH = 2;
@@ -88,11 +94,9 @@ const ITEM_WIDTH = 2;
 let style = `
   .ProgressBar-number-of,
   .ProgressBar-percent {
-    flex: 0 0 auto;
     white-space: nowrap;
-    padding-right: 0.5em;
-    padding-left: 0.25em;
-    text-align: right;
+    padding-right: 0.3em;
+    text-align: left;
     transition: width .25s ease;
   }
 
@@ -164,10 +168,20 @@ const ProgressBar: React.FC<Props> = (props) => {
   /* ---------------- Sizes --------------- */
   /*----------------------------------------*/
 
+  // Add dynamic general style
+  style += `
+    .ProgressBar-percent {
+      min-width: ${(status.usePercent ? status.numDecimalPlaces ?? 0 : 0) + PERCENT_WIDTH}em;
+    }
+    .ProgressBar-number-of {
+      min-width: ${((!status.usePercent ? String(status.total ?? 0).length || 1 : 0) * ITEM_WIDTH_MULTIPLIER) + ITEM_WIDTH}em;
+    }
+  `;
+
   // Size styles
   switch (size) {
-    case ProgressBarSize.Small:
-      // Small size
+    case ProgressBarSize.Medium:
+      // Medium size
       style += `
         .ProgressBar-container .ProgressBar-number-of, .ProgressBar-container .ProgressBar-percent {
           font-size: 1em;
@@ -180,18 +194,10 @@ const ProgressBar: React.FC<Props> = (props) => {
           height: 1.5em;
           border-radius: 0.5em;
         }
-        .ProgressBar-percent {
-          min-width: ${((status.usePercent ? status.numDecimalPlaces ?? 0 : 0) * 1) + PERCENT_WIDTH}em;
-          max-width: ${((status.usePercent ? status.numDecimalPlaces ?? 0 : 0) * 1) + PERCENT_WIDTH}em;
-        }
-        .ProgressBar-number-of {
-          min-width: ${((!status.usePercent ? status.total?.toString().length || 1 : 0) * ITEM_WIDTH_MULTIPLIER) + ITEM_WIDTH}em;
-          max-width: ${((!status.usePercent ? status.total?.toString().length || 1 : 0) * ITEM_WIDTH_MULTIPLIER) + ITEM_WIDTH}em;
-        }
       `;
       break;
-    case ProgressBarSize.Medium:
-      // Medium size
+    case ProgressBarSize.Large:
+      // Large size
       style += `
         .ProgressBar-container .ProgressBar-number-of, .ProgressBar-container .ProgressBar-percent {
           font-size: 1.5em;
@@ -204,38 +210,6 @@ const ProgressBar: React.FC<Props> = (props) => {
           height: 2em;
           border-radius: 0.7em;
         }
-        .ProgressBar-percent {
-          min-width: ${((status.usePercent ? status.numDecimalPlaces ?? 0 : 0) * 1) + PERCENT_WIDTH}em;
-          max-width: ${((status.usePercent ? status.numDecimalPlaces ?? 0 : 0) * 1) + PERCENT_WIDTH}em;
-        }
-        .ProgressBar-number-of {
-          min-width: ${((!status.usePercent ? status.total?.toString().length || 1 : 0) * ITEM_WIDTH_MULTIPLIER) + ITEM_WIDTH}em;
-          max-width: ${((!status.usePercent ? status.total?.toString().length || 1 : 0) * ITEM_WIDTH_MULTIPLIER) + ITEM_WIDTH}em;
-        }
-      `;
-      break;
-    case ProgressBarSize.Large:
-      // Large size
-      style += `
-        .ProgressBar-container .ProgressBar-number-of, .ProgressBar-container .ProgressBar-percent {
-          font-size: 2em;
-        }
-        .ProgressBar-container .ProgressBar-background {
-          height: 3em;
-          border-radius: 1em;
-        }
-        .ProgressBar-container .ProgressBar-bar {
-          height: 3em;
-          border-radius: 1em;
-        }
-        .ProgressBar-percent {
-          min-width:  ${((status.usePercent ? status.numDecimalPlaces ?? 0 : 0) * 1) + PERCENT_WIDTH}em;
-          max-width:  ${((status.usePercent ? status.numDecimalPlaces ?? 0 : 0) * 1) + PERCENT_WIDTH}em;
-        }
-        .ProgressBar-number-of {
-          min-width: ${((!status.usePercent ? status.total?.toString().length || 1 : 0) * ITEM_WIDTH_MULTIPLIER) + ITEM_WIDTH}em;
-          max-width: ${((!status.usePercent ? status.total?.toString().length || 1 : 0) * ITEM_WIDTH_MULTIPLIER) + ITEM_WIDTH}em;
-        }
       `;
       break;
     default:
@@ -245,9 +219,8 @@ const ProgressBar: React.FC<Props> = (props) => {
   // Get the width of the outline based on size
   const outlineWidth = (() => {
     switch (size) {
-      case ProgressBarSize.Small: return '0.05em';
-      case ProgressBarSize.Medium: return '0.08em';
-      case ProgressBarSize.Large: return '0.1em';
+      case ProgressBarSize.Medium: return '0.05em';
+      case ProgressBarSize.Large: return '0.08em';
       default: return '0.05em';
     }
   })();
@@ -275,25 +248,38 @@ const ProgressBar: React.FC<Props> = (props) => {
   `;
 
   // Stripes for striped effect
-  const stripes: React.ReactNode = (
-    <div>
-      <style>{stripesStyle}</style>
-      <div
-        className="ProgressBar-stripes position-absolute "
-        style={{
-          width: '200%',
-          height: '100%',
-        }}
-      >
-        &nbsp;
+  let stripes: React.ReactNode = null;
+  if (striped) {
+    stripes = (
+      <div>
+        <style>{stripesStyle}</style>
+        <div
+          className="ProgressBar-stripes position-absolute"
+          style={{
+            width: '200%',
+            height: '100%',
+          }}
+        >
+          &nbsp;
+        </div>
       </div>
-    </div>
-  );
+    );
+  }
 
   /*----------------------------------------*/
   /* --------------- Main UI -------------- */
   /*----------------------------------------*/
 
+  // Calculate the width of the progress bar
+  let progressBarWidthPercent = 0;
+  if (status.usePercent) {
+    // Use percent progress directly
+    progressBarWidthPercent = status.percentProgress;
+  } else if (status.total > 0) {
+    // Calculate percent progress from items
+    progressBarWidthPercent = (status.numComplete / status.total) * 100;
+  }
+
   // Render the progress bar
   return (
     <div className="ProgressBar-container d-flex align-items-center">
@@ -301,25 +287,27 @@ const ProgressBar: React.FC<Props> = (props) => {
       <style>{style}</style>
       {/* Use items */}
       {!status.usePercent && status.numComplete && (
-        <span
-          className="ProgressBar-number-of pe-2 align-self-center"
-        >
+        <span className="ProgressBar-number-of">
           {status.numComplete}
           &nbsp;of&nbsp;
           {status.total}
         </span>
       )}
       {/* Use percentage */}
-      {status.usePercent && status.percentProgress && (
-        <span
-          className="ProgressBar-percent pe-2 align-self-center"
-        >
-          {status.percentProgress.toFixed(status?.numDecimalPlaces ?? 0)}
+      {status.usePercent && (
+        <span className="ProgressBar-percent">
+          {
+            padDecimalZeros(
+              roundToNumDecimals(status.percentProgress ?? 0, status?.numDecimalPlaces ?? 0),
+              status?.numDecimalPlaces ?? 0,
+            )
+          }
           %
         </span>
       )}
+      {/* Progress Bar Filled Area */}
       <div
-        className={`ProgressBar-background bg-${bgVariant} w-100`}
+        className={`ProgressBar-background bg-${bgVariant} flex-grow-1`}
         style={{
           boxShadow: `0 0 0 ${outlineWidth} ${showOutline ? '#000' : '#DEE2E6'}`,
         }}
@@ -332,11 +320,13 @@ const ProgressBar: React.FC<Props> = (props) => {
             `ProgressBar-bar bg-${variant} text-start position-relative`
           }
           style={{
-            width: `${(status.usePercent ? status.percentProgress : (status.numComplete / status.total) * 100)}%`,
+            width: `${progressBarWidthPercent}%`,
             overflow: 'hidden',
           }}
         >
-          {striped && stripes}
+          {/* Show Strips (if they exist) */}
+          {stripes}
+          {/* Space so the bar has some content */}
           &nbsp;
         </div>
       </div>

package/src/index.ts

@@ -103,6 +103,7 @@ import AutoscrollToBottomContainer from './components/AutoscrollToBottomContaine
 import MultiSwitch from './components/MultiSwitch';
 import Dropdown from './components/Dropdown';
 import ProgressBar from './components/ProgressBar';
+import FakeProgressBar from './components/FakeProgressBar';
 
 // Import dynamic constants
 import DynamicWord from './dynamicConstants/DynamicWord';
@@ -163,6 +164,7 @@ export {
   MultiSwitch,
   Dropdown,
   ProgressBar,
+  FakeProgressBar,
   // Global functions
   alert,
   prompt,

package/src/types/ProgressBarSize.ts

@@ -3,7 +3,6 @@
  * @author Allison Zhang
  */
 enum ProgressBarSize {
-  Small = 'Small',
   Medium = 'Medium',
   Large = 'Large',
 }