dce-reactkit 2.0.10 → 3.0.0

package/lib/index.d.ts

@@ -0,0 +1,274 @@
+/// <reference types="react" />
+import React from 'react';
+
+/**
+ * A wrapper for the entire React app that adds global functionality like
+ *   handling for fatal error messages
+ * @author Gabe Abrams
+ */
+
+declare type Props$3 = {
+    children: React.ReactNode;
+    dark?: boolean;
+    sessionExpiredMessage?: string;
+};
+/**
+ * Show an alert modal with an "Okay" button
+ * @author Gabe Abrams
+ * @param title the title text to display at the top of the alert
+ * @param text the text to display in the alert
+ */
+declare const alert: (title: string, text: string) => Promise<unknown>;
+/**
+ * Show a confirmation modal with an "Okay" and a "Cancel" button
+ * @author Gabe Abrams
+ * @param title the title text to display at the top of the alert
+ * @param text the text to display in the alert
+ * @returns true if the user confirmed
+ */
+declare const confirm: (title: string, text: string) => Promise<boolean>;
+/**
+ * Show a fatal error message
+ * @author Gabe Abrams
+ * @param error the error to show
+ * @param [errorTitle] title of the error box
+ */
+declare const showFatalError: (error: any, errorTitle?: string) => Promise<unknown> | undefined;
+declare const AppWrapper: React.FC<Props$3>;
+
+/**
+ * Loading spinner/indicator
+ * @author Gabe Abrams
+ */
+declare const LoadingSpinner: () => JSX.Element;
+
+/**
+ * Displays an error
+ * @author Gabe Abrams
+ */
+
+declare type Props$2 = {
+    error: any;
+    title?: string;
+    onClose?: () => void;
+};
+declare const ErrorBox: React.FC<Props$2>;
+
+/**
+ * Bootstrap variants
+ * @author Gabe Abrams
+ */
+declare enum Variant {
+    Primary = "primary",
+    Secondary = "secondary",
+    Success = "success",
+    Warning = "warning",
+    Info = "info",
+    Danger = "danger",
+    Light = "light",
+    Dark = "dark"
+}
+
+/**
+ * Types of buttons in the modal
+ * @author Gabe Abrams
+ */
+declare enum ModalButtonType {
+    Okay = "okay",
+    Cancel = "cancel",
+    Yes = "yes",
+    No = "no",
+    Abandon = "abandon",
+    GoBack = "goBack",
+    Continue = "continue",
+    ImSure = "imSure",
+    Delete = "delete",
+    Confirm = "confirm"
+}
+
+/**
+ * Modal sizes
+ * @author Gabe Abrams
+ */
+declare enum ModalSize {
+    Small = "sm",
+    Medium = "md",
+    Large = "lg",
+    ExtraLarge = "xl"
+}
+
+/**
+ * Types of modals
+ * @author Gabe Abrams
+ */
+declare enum ModalType {
+    Okay = "okay",
+    OkayCancel = "okay-cancel",
+    YesNo = "yes-no",
+    YesNoCancel = "yes-no-cancel",
+    AbandonGoBack = "abandon-goBack",
+    ImSureCancel = "imSure-cancel",
+    DeleteCancel = "delete-cancel",
+    ConfirmCancel = "confirm-cancel",
+    NoButtons = "-"
+}
+
+/**
+ * A generic popup modal
+ * @author Gabe Abrams
+ */
+
+declare type Props$1 = {
+    type?: ModalType;
+    size?: ModalSize;
+    title?: React.ReactNode;
+    children?: React.ReactNode;
+    onClose?: (type: ModalButtonType) => void;
+    dontAllowBackdropExit?: boolean;
+    okayLabel?: string;
+    okayVariant?: Variant;
+    cancelLabel?: string;
+    cancelVariant?: Variant;
+    yesLabel?: string;
+    yesVariant?: Variant;
+    noLabel?: string;
+    noVariant?: Variant;
+    abandonLabel?: string;
+    abandonVariant?: Variant;
+    goBackLabel?: string;
+    goBackVariant?: Variant;
+    continueLabel?: string;
+    continueVariant?: Variant;
+    imSureLabel?: string;
+    imSureVariant?: Variant;
+    deleteLabel?: string;
+    deleteVariant?: Variant;
+    confirmLabel?: string;
+    confirmVariant?: Variant;
+    onTopOfOtherModals?: boolean;
+};
+declare const Modal: React.FC<Props$1>;
+
+/**
+ * A box with a tab on the top that holds buttons and other content
+ * @author Gabe Abrams
+ */
+
+declare type Props = {
+    title: React.ReactNode;
+    children: React.ReactNode;
+};
+declare const TabBox: React.FC<Props>;
+
+/**
+ * An error with a code
+ * @author Gabe Abrams
+ */
+declare class ErrorWithCode extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+
+/**
+ * Shorten text so it fits into a certain number of chars
+ * @author Gabe Abrams
+ * @param text the text to abbreviate
+ * @param maxChars the maximum number of chars to include
+ * @returns abbreviated text with length no greater than maxChars
+ *   (including ellipses if applicable)
+ */
+declare const abbreviate: (text: string, maxChars: number) => string;
+
+/**
+ * Get the average of a set of numbers
+ * @author Gabe Abrams
+ * @param nums the numbers to average
+ * @returns average value or 0 if no numbers
+ */
+declare const avg: (nums: number[]) => number;
+
+/**
+ * Round a number (ceiling) to a certain number of decimals
+ * @author Gabe Abrams
+ * @param num the number to round
+ * @param numDecimals the number of decimals to round to
+ * @returns rounded number
+ */
+declare const ceilToNumDecimals: (num: number, numDecimals: number) => number;
+
+/**
+ * Round a number (floor) to a certain number of decimals
+ * @author Gabe Abrams
+ * @param num the number to round
+ * @param numDecimals the number of decimals to round to
+ * @returns rounded number
+ */
+declare const floorToNumDecimals: (num: number, numDecimals: number) => number;
+
+/**
+ * Force a number to stay within specific bounds
+ * @author Gabe Abrams
+ * @param num the number to move into the bounds
+ * @param min the minimum number in the bound
+ * @param max the maximum number in the bound
+ * @returns bounded number
+ */
+declare const forceNumIntoBounds: (num: number, min: number, max: number) => number;
+
+/**
+ * Pad a number's decimal with zeros on the right
+ *   (e.g. 5.2 becomes 5.20 with 2 digit padding)
+ * @author Gabe Abrams
+ * @param num the number to pad
+ * @param numDigits the minimum number of digits after the decimal
+ * @returns padded number
+ */
+declare const padDecimalZeros: (num: number, numDigits: number) => string;
+
+/**
+ * Pad a number with zeros on the left (e.g. 5 becomes 05 with 2 digit padding)
+ * @author Gabe Abrams
+ * @param num the number to pad
+ * @param numDigits the minimum number of digits before the decimal
+ * @returns padded number
+ */
+declare const padZerosLeft: (num: number, numDigits: number) => string;
+
+/**
+ * Round a number to a certain number of decimals
+ * @author Gabe Abrams
+ * @param num the number to round
+ * @param numDecimals the number of decimals to round to
+ * @returns rounded number
+ */
+declare const roundToNumDecimals: (num: number, numDecimals: number) => number;
+
+/**
+ * Sum the numbers in an array
+ * @author Gabe Abrams
+ * @param nums the numbers to sum
+ * @returns the sum of the numbers
+ */
+declare const sum: (nums: number[]) => number;
+
+/**
+ * Wait for a certain number of ms
+ * @author Gabe Abrams
+ * @param ms number of ms to wait
+ */
+declare const waitMs: (ms?: number) => Promise<unknown>;
+
+/**
+ * List of error codes built into the react kit
+ * @author Gabe Abrams
+ */
+declare enum ReactKitErrorCode {
+    NoResponse = "DRK1",
+    NoCode = "DRK2",
+    SessionExpired = "DRK3",
+    MissingParameter = "DRK4",
+    InvalidParameter = "DRK5",
+    WrongCourse = "DRK6"
+}
+
+export { AppWrapper, ErrorBox, ErrorWithCode, LoadingSpinner, Modal, ModalButtonType, ModalSize, ModalType, ReactKitErrorCode, TabBox, Variant, abbreviate, alert, avg, ceilToNumDecimals, confirm, floorToNumDecimals, forceNumIntoBounds, padDecimalZeros, padZerosLeft, roundToNumDecimals, showFatalError, sum, waitMs };

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "dce-reactkit",
-  "version": "2.0.10",
-  "main": "index.js",
-  "module": "index.js",
+  "version": "3.0.0",
+  "main": "lib/cjs/index.js",
+  "module": "lib/esm/index.js",
+  "types": "lib/index.d.ts",
   "scripts": {
-    "build": "tsc --project ./tsconfig.json"
+    "build": "rollup -c"
   },
   "repository": {
     "type": "git",
@@ -19,10 +20,16 @@
     "@fortawesome/free-solid-svg-icons": "^6.1.1",
     "@fortawesome/react-fontawesome": "^0.1.18",
     "caccl": "^2.0.0-beta.39",
-    "react-bootstrap": "^2.2.3"
+    "react-bootstrap": "^2.2.3",
+    "react": "^18.0.0"
   },
   "devDependencies": {
+    "@rollup/plugin-commonjs": "^21.1.0",
+    "@rollup/plugin-json": "^4.1.0",
+    "@rollup/plugin-node-resolve": "^13.2.1",
+    "@rollup/plugin-typescript": "^8.3.2",
     "@types/express": "^4.17.13",
+    "@types/react": "^18.0.5",
     "@typescript-eslint/eslint-plugin": "^5.18.0",
     "@typescript-eslint/parser": "^5.18.0",
     "eslint": "^8.12.0",
@@ -33,6 +40,20 @@
     "eslint-plugin-jsx-a11y": "^6.5.1",
     "eslint-plugin-react": "^7.29.4",
     "eslint-plugin-react-hooks": "^4.4.0",
+    "react": "^18.0.0",
+    "rollup": "^2.70.2",
+    "rollup-plugin-dts": "^4.2.1",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-terser": "^7.0.2",
     "typescript": "^4.6.3"
+  },
+  "peerDependencies": {
+    "@fortawesome/fontawesome-svg-core": "^6.1.1",
+    "@fortawesome/free-regular-svg-icons": "^6.1.1",
+    "@fortawesome/free-solid-svg-icons": "^6.1.1",
+    "@fortawesome/react-fontawesome": "^0.1.18",
+    "caccl": "^2.0.0-beta.39",
+    "react-bootstrap": "^2.2.3",
+    "react": "^18.0.0"
   }
 }

package/rollup.config.js

@@ -0,0 +1,43 @@
+import resolve from "@rollup/plugin-node-resolve";
+import commonjs from "@rollup/plugin-commonjs";
+import typescript from "@rollup/plugin-typescript";
+import dts from "rollup-plugin-dts";
+import { terser } from "rollup-plugin-terser";
+import peerDepsExternal from 'rollup-plugin-peer-deps-external';
+import json from "@rollup/plugin-json";
+
+const packageJson = require("./package.json");
+
+export default [
+  {
+    input: "src/index.ts",
+    output: [
+      {
+        file: packageJson.main,
+        format: "cjs",
+        sourcemap: true,
+      },
+      {
+        file: packageJson.module,
+        format: "esm",
+        sourcemap: true,
+      },
+    ],
+    plugins: [
+      peerDepsExternal(),
+      resolve({
+        preferBuiltins: false,
+      }),
+      commonjs(),
+      typescript({ tsconfig: "./tsconfig.json" }),
+      terser(),
+      json(),
+    ],
+    external: ["react", "react-dom", "styled-components"]
+  },
+  {
+    input: "lib/esm/types/index.d.ts",
+    output: [{ file: "lib/index.d.ts", format: "esm" }],
+    plugins: [dts()],
+  },
+];

package/src/components/AppWrapper.tsx

@@ -5,16 +5,18 @@
  */
 
 // Import React
-import React, { useState, useEffect } from 'react';
+import React, { useState } from 'react';
 
 // Import shared components
 import ErrorBox from './ErrorBox';
 
-// Import helpers
-import { setSessionExpiryHandler } from '../helpers/visitServerEndpoint';
-
 // Import shared types
 import ReactKitErrorCode from '../types/ReactKitErrorCode';
+import ModalButtonType from '../types/ModalButtonType';
+import ModalType from '../types/ModalType';
+
+// Import shared components
+import Modal from './Modal';
 
 // Import custom errors
 import ErrorWithCode from '../errors/ErrorWithCode';
@@ -36,6 +38,84 @@ type Props = {
 /*                             Static Helpers                             */
 /*------------------------------------------------------------------------*/
 
+/*----------------------------------------*/
+/*                  Alert                 */
+/*----------------------------------------*/
+
+// Stored copies of setters
+let setAlertInfo: (info: { title: string, text: string }) => void;
+let onAlertClosed: () => void;
+
+/**
+ * Show an alert modal with an "Okay" button
+ * @author Gabe Abrams
+ * @param title the title text to display at the top of the alert
+ * @param text the text to display in the alert
+ */
+export const alert = async (title: string, text: string) => {
+  // Fallback if alert not available
+  if (!setAlertInfo) {
+    return window.alert(`${title}\n\n${text}`);
+  }
+
+  // Return promise that resolves when alert is closed
+  return new Promise((resolve) => {
+    // Setup handler
+    onAlertClosed = () => {
+      resolve(null);
+    };
+
+    // Show the alert
+    setAlertInfo({
+      title,
+      text,
+    });
+  });
+};
+
+/*----------------------------------------*/
+/*                 Confirm                */
+/*----------------------------------------*/
+
+// Stored copies of setters
+let setConfirmInfo: (info: { title: string, text: string }) => void;
+let onConfirmClosed: (confirmed: boolean) => void;
+
+/**
+ * Show a confirmation modal with an "Okay" and a "Cancel" button
+ * @author Gabe Abrams
+ * @param title the title text to display at the top of the alert
+ * @param text the text to display in the alert
+ * @returns true if the user confirmed
+ */
+export const confirm = async (
+  title: string,
+  text: string,
+): Promise<boolean> => {
+  // Fallback if confirm is not available
+  if (!setConfirmInfo) {
+    return window.confirm(`${title}\n\n${text}`);
+  }
+
+  // Return promise that resolves with result of confirmation
+  return new Promise((resolve) => {
+    // Setup handler
+    onConfirmClosed = (confirmed: boolean) => {
+      resolve(confirmed)
+    };
+
+    // Show the confirm
+    setConfirmInfo({
+      title,
+      text,
+    });
+  });
+};
+
+/*----------------------------------------*/
+/*               Fatal Error              */
+/*----------------------------------------*/
+
 // Stored copies of setters
 let setFatalErrorMessage: (message: string) => void;
 let setFatalErrorCode: (code: string) => void;
@@ -65,7 +145,10 @@ export const showFatalError = (
 
   // Handle case where app hasn't loaded
   if (!setFatalErrorMessage || !setFatalErrorCode) {
-    return alert(`An error has occurred: ${message} (code: ${code}). Please contact support.`);
+    return alert(
+      errorTitle,
+      `${message} (code: ${code}). Please contact support.`,
+    );
   }
 
   // Use setters
@@ -74,11 +157,26 @@ export const showFatalError = (
   setFatalErrorTitle(errorTitle);
 };
 
+/*----------------------------------------*/
+/*             Session Expired            */
+/*----------------------------------------*/
+
+// Stored copies of setters
+let setSessionHasExpired: (isExpired: boolean) => void;
+
+/**
+ * Show the "session expired" message
+ * @author Gabe Abrams
+ */
+export const showSessionExpiredMessage = () => {
+  setSessionHasExpired(true);
+};
+
 /*------------------------------------------------------------------------*/
 /*                                Component                               */
 /*------------------------------------------------------------------------*/
 
-const AppWrapper = (props: Props): React.ReactElement => {
+const AppWrapper: React.FC<Props> = (props: Props): React.ReactElement => {
   /*------------------------------------------------------------------------*/
   /*                                  Setup                                 */
   /*------------------------------------------------------------------------*/
@@ -94,51 +192,115 @@ const AppWrapper = (props: Props): React.ReactElement => {
   /* -------------- State ------------- */
 
   // Fatal error
-  const [fatalErrorMessage, setFatalErrorMessageInner] = useState(null);
+  const [
+    fatalErrorMessage,
+    setFatalErrorMessageInner,
+  ] = useState<string | undefined>();
   setFatalErrorMessage = setFatalErrorMessageInner;
-  const [fatalErrorCode, setFatalErrorCodeInner] = useState(null);
+  const [
+    fatalErrorCode,
+    setFatalErrorCodeInner,
+  ] = useState<string | undefined>();
   setFatalErrorCode = setFatalErrorCodeInner;
-  const [fatalErrorTitle, setFatalErrorTitleInner] = useState(null);
+  const [
+    fatalErrorTitle,
+    setFatalErrorTitleInner,
+  ] = useState<string | undefined>();
   setFatalErrorTitle = setFatalErrorTitleInner;
 
-  // Session expired
-  const [sessionHasExpired, setSessionHasExpired] = useState(false);
+  // Alert
+  const [
+    alertInfo,
+    setAlertInfoInner,
+  ] = useState<{
+    title: string,
+    text: string
+  }>();
+  setAlertInfo = setAlertInfoInner;
 
-  /*------------------------------------------------------------------------*/
-  /*                           Lifecycle Functions                          */
-  /*------------------------------------------------------------------------*/
+  // Confirm
+  const [
+    confirmInfo,
+    setConfirmInfoInner,
+  ] = useState<{
+    title: string,
+    text: string
+  }>();
+  setConfirmInfo = setConfirmInfoInner;
 
-  /**
-   * Mount
-   * @author Gabe Abrams
-   */
-  useEffect(
-    () => {
-      // Add session expired handler
-      setSessionExpiryHandler(() => {
-        // Session expired!
-        setSessionHasExpired(true);
-      });
-    },
-    [],
-  );
+  // Session expired
+  const [
+    sessionHasExpired,
+    setSessionHasExpiredInner,
+  ] = useState<boolean>(false);
+  setSessionHasExpired = setSessionHasExpiredInner;
 
   /*------------------------------------------------------------------------*/
   /*                                 Render                                 */
   /*------------------------------------------------------------------------*/
 
   /*----------------------------------------*/
-  /*                 Main UI                */
+  /*                  Modal                 */
+  /*----------------------------------------*/
+
+  // Modal that may be defined
+  let modal: React.ReactNode;
+
+  /* -------------- Alert ------------- */
+
+  if (alertInfo) {
+    modal = (
+      <Modal
+        title={alertInfo.title}
+        type={ModalType.Okay}
+        onClose={() => {
+          // Alert closed
+          if (onAlertClosed) {
+            onAlertClosed();
+          }
+        }}
+        onTopOfOtherModals
+      >
+        {alertInfo.text}
+      </Modal>
+    );
+  }
+
+  /* ------------- Confirm ------------ */
+
+  if (confirmInfo) {
+    modal = (
+      <Modal
+        title={confirmInfo.title}
+        type={ModalType.OkayCancel}
+        onClose={(buttonType) => {
+          if (onConfirmClosed) {
+            onConfirmClosed(buttonType === ModalButtonType.Okay);
+          }
+        }}
+        dontAllowBackdropExit
+      >
+
+      </Modal>
+    );
+  }
+
+  /*----------------------------------------*/
+  /*                  Views                 */
   /*----------------------------------------*/
 
-  // Show error
+  // Body that will be filled with the current view
+  let body: React.ReactNode;
+
+  /* ----------- Fatal Error ---------- */
+
   if (fatalErrorMessage || fatalErrorCode || sessionHasExpired) {
     // Re-encapsulate in an error
     const error = (
       sessionHasExpired
         ? new ErrorWithCode(
-          fatalErrorMessage,
-          fatalErrorCode,
+          (fatalErrorMessage ?? 'An unknown error has occurred. Please contact support.'),
+          (fatalErrorCode ?? ReactKitErrorCode.NoCode),
         )
         : new ErrorWithCode(
           sessionExpiredMessage,
@@ -147,13 +309,13 @@ const AppWrapper = (props: Props): React.ReactElement => {
     );
 
     // Build error screen
-    return (
+    body = (
       <div
         style={{
           display: 'block',
           width: '100vw',
           minHeight: '100vh',
-          paddingTop: '10rem',
+          paddingTop: '2rem',
           backgroundColor: (
             dark
               ? '#222'
@@ -173,10 +335,24 @@ const AppWrapper = (props: Props): React.ReactElement => {
     );
   }
 
-  // Show the app itself
+  /* --------------- App -------------- */
+
+  if (!body) {
+    body = (
+      <>
+        {children}
+      </>
+    );
+  }
+
+  /*----------------------------------------*/
+  /*                 Main UI                */
+  /*----------------------------------------*/
+
   return (
     <>
-      {children}
+      {modal}
+      {body}
     </>
   );
 };