dce-reactkit 3.8.3 → 3.8.4

package/dist/cjs/types/components/Dropdown.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A simple dropdown menu
+ * @author Alessandra De Lucas
+ * @author Gabe Abrams
+ * @author Yuen Ler Chow
+ */
+import React from 'react';
+import Variant from '../types/Variant';
+import DropdownItemType from '../types/DropdownItemType';
+type Props = {
+    items: DropdownItem[];
+    variant?: Variant;
+    dropdownButton: {
+        ariaLabel: string;
+        id: string;
+        content?: React.ReactNode;
+    };
+};
+type DropdownItem = ({
+    type: DropdownItemType.Header;
+    content: React.ReactNode;
+} | {
+    type: DropdownItemType.Divider;
+} | {
+    type: DropdownItemType.Item;
+    content: React.ReactNode;
+    ariaLabel: string;
+    id: string;
+    onClick: () => void;
+});
+declare const Dropdown: React.FC<Props>;
+export default Dropdown;

package/dist/cjs/types/helpers/validators/ChicagoTitleCase.d.ts

@@ -0,0 +1,9 @@
+/**
+ * This function converts a string to title case based on Chicago Title Case
+ * Style rules.
+ * @author Leisha Bhandari
+ * @param input: The input string that needs to be converted to Chicago title
+ *               case.
+ * @returns Input string converted to title case
+ */
+declare const chicagoTitleCase: (input: string) => string;

package/dist/cjs/types/helpers/validators/validURL.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This function checks if a given input string is a valid URL.
+ * @author Leisha Bhandari
+ * @param URL: The input string that needs checked as a URL or not.
+ * @returns A true boolean value if the input string is a valid URL, and a false
+ *          boolean value if the input string is a invalid URL
+ */
+declare function isValid(url: string): boolean;

package/dist/cjs/types/types/DropdownItemType.d.ts

@@ -0,0 +1,6 @@
+declare enum DropdownItemType {
+    Header = "Header",
+    Divider = "Divider",
+    Item = "Item"
+}
+export default DropdownItemType;

package/dist/esm/types/components/Dropdown.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A simple dropdown menu
+ * @author Alessandra De Lucas
+ * @author Gabe Abrams
+ * @author Yuen Ler Chow
+ */
+import React from 'react';
+import Variant from '../types/Variant';
+import DropdownItemType from '../types/DropdownItemType';
+type Props = {
+    items: DropdownItem[];
+    variant?: Variant;
+    dropdownButton: {
+        ariaLabel: string;
+        id: string;
+        content?: React.ReactNode;
+    };
+};
+type DropdownItem = ({
+    type: DropdownItemType.Header;
+    content: React.ReactNode;
+} | {
+    type: DropdownItemType.Divider;
+} | {
+    type: DropdownItemType.Item;
+    content: React.ReactNode;
+    ariaLabel: string;
+    id: string;
+    onClick: () => void;
+});
+declare const Dropdown: React.FC<Props>;
+export default Dropdown;

package/dist/esm/types/helpers/validators/ChicagoTitleCase.d.ts

@@ -0,0 +1,9 @@
+/**
+ * This function converts a string to title case based on Chicago Title Case
+ * Style rules.
+ * @author Leisha Bhandari
+ * @param input: The input string that needs to be converted to Chicago title
+ *               case.
+ * @returns Input string converted to title case
+ */
+declare const chicagoTitleCase: (input: string) => string;

package/dist/esm/types/helpers/validators/validURL.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This function checks if a given input string is a valid URL.
+ * @author Leisha Bhandari
+ * @param URL: The input string that needs checked as a URL or not.
+ * @returns A true boolean value if the input string is a valid URL, and a false
+ *          boolean value if the input string is a invalid URL
+ */
+declare function isValid(url: string): boolean;

package/dist/esm/types/types/DropdownItemType.d.ts

@@ -0,0 +1,6 @@
+declare enum DropdownItemType {
+    Header = "Header",
+    Divider = "Divider",
+    Item = "Item"
+}
+export default DropdownItemType;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dce-reactkit",
-  "version": "3.8.3",
+  "version": "3.8.4",
   "description": "Shared components for Harvard DCE apps",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/components/Dropdown.tsx

@@ -0,0 +1,308 @@
+/**
+ * A simple dropdown menu
+ * @author Alessandra De Lucas
+ * @author Gabe Abrams
+ * @author Yuen Ler Chow
+ */
+
+// Import React
+import React, { useEffect, useReducer, useRef } from 'react';
+
+// Import helpers
+import combineClassNames from '../helpers/combineClassNames';
+
+// Import shared types
+import Variant from '../types/Variant';
+import DropdownItemType from '../types/DropdownItemType';
+
+/*------------------------------------------------------------------------*/
+/* -------------------------------- Types ------------------------------- */
+/*------------------------------------------------------------------------*/
+
+// Props definition
+type Props = {
+  // List of items in the dropdown menu
+  items: DropdownItem[],
+  // If true, dropdown variant is displayed
+  variant?: Variant,
+  // Information about the dropdown button
+  dropdownButton: {
+    // Aria label for accessibility
+    ariaLabel: string,
+    // Unique ID
+    id: string,
+    // Button content
+    content?: React.ReactNode,
+  },
+  // If true, no arrow shows in dropdown
+  // noArrow?: boolean,
+  // Size of dropdown
+  // size?: DropdownSize,
+  // Direction of dropdown
+  // direction?: DropdownDirection,
+};
+
+// Details about a dropdown item
+type DropdownItem = (
+  | {
+    // Header element
+    type: DropdownItemType.Header,
+    // Header content
+    content: React.ReactNode,
+  }
+  | {
+    // Divider element
+    type: DropdownItemType.Divider,
+  }
+  | {
+    // Item from dropdown menu
+    type: DropdownItemType.Item,
+    // Item content
+    content: React.ReactNode,
+    // Item aria label
+    ariaLabel: string,
+    // Unique item ID
+    id: string,
+    // Click function for dropdown item
+    onClick: () => void,
+  }
+);
+
+// Dropdown menu sizes
+// enum DropdownSize {
+//   // Small dropdown size
+//   Small = 'Small',
+//   // Medium dropdown size
+//   Medium = 'Medium',
+//   // Large dropdown size
+//   Large = 'Large',
+// }
+
+// Dropdown menu direction
+// enum DropdownDirection {
+//   // Dropdown menu appears centered
+//   Centered = 'Centered',
+//   // Dropdown menu appears to right of button
+//   Right = 'Right',
+//   // Dropdown menu appears to left of button
+//   Left = 'Left',
+//   // Dropdown menu appears above the button
+//   Up = 'Up',
+//   // Dropdown menu appears below the button
+//   Down = 'Down',
+// }
+
+/*------------------------------------------------------------------------*/
+/* -------------------------------- State ------------------------------- */
+/*------------------------------------------------------------------------*/
+
+/* -------- State Definition -------- */
+
+type State = {
+  // If true, the dropdown menu is open
+  isDropdownOpen: boolean,
+};
+
+/* ------------- Actions ------------ */
+
+// Types of actions
+enum ActionType {
+  // Toggle opening the dropdown menu
+  ToggleDropdown = 'ToggleDropdown',
+  // Close the dropdown menu
+  CloseDropdown = 'CloseDropdown',
+}
+
+// Action definitions
+type Action = (
+  | {
+    type: ActionType.ToggleDropdown,
+  }
+  | {
+    type: ActionType.CloseDropdown,
+  }
+);
+
+/**
+ * Reducer that executes actions
+ * @author Alessandra De Lucas
+ * @param state current state
+ * @param action action to execute
+ */
+const reducer = (state: State, action: Action): State => {
+  switch (action.type) {
+    case ActionType.ToggleDropdown: {
+      return {
+        ...state,
+        isDropdownOpen: !state.isDropdownOpen,
+      };
+    }
+    case ActionType.CloseDropdown: {
+      return {
+        ...state,
+        isDropdownOpen: false,
+      };
+    }
+    default: {
+      return state;
+    }
+  }
+};
+
+/*------------------------------------------------------------------------*/
+/* ------------------------------ Component ----------------------------- */
+/*------------------------------------------------------------------------*/
+
+const Dropdown: React.FC<Props> = (props) => {
+  /*------------------------------------------------------------------------*/
+  /* -------------------------------- Setup ------------------------------- */
+  /*------------------------------------------------------------------------*/
+
+  /* -------------- Props ------------- */
+
+  // Destructure all props
+  const {
+    dropdownButton,
+    items,
+    variant = Variant.Secondary,
+  } = props;
+
+  /* -------------- State ------------- */
+
+  // Initial state
+  const initialState: State = {
+    isDropdownOpen: false,
+  };
+
+  // Initialize state
+  const [state, dispatch] = useReducer(reducer, initialState);
+
+  // Destructure common state
+  const {
+    isDropdownOpen,
+  } = state;
+
+  /* -------------- Refs -------------- */
+
+  // Initialize refs
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  /*------------------------------------------------------------------------*/
+  /* ------------------------- Component Functions ------------------------ */
+  /*------------------------------------------------------------------------*/
+
+  /**
+   * Handle clicking outside of the dropdown menu to close it
+   * @author Yuen Ler Chow
+   * @param event the mouse event
+   */
+  const handleClickOutside = (event: MouseEvent) => {
+    if (
+      dropdownRef.current && !dropdownRef.current.contains(event.target as Node)
+    ) {
+      dispatch({ type: ActionType.CloseDropdown });
+    }
+  };
+
+  /*------------------------------------------------------------------------*/
+  /* ------------------------- Lifecycle Functions ------------------------ */
+  /*------------------------------------------------------------------------*/
+
+  /**
+   * Mount
+   * @author Yuen Ler Chow
+   */
+  useEffect(() => {
+    // Add event listener to close dropdown when clicking outside
+    document.addEventListener('mousedown', handleClickOutside);
+
+    // Cleanup
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+    };
+  }, []);
+
+  /*----------------------------------------*/
+  /* --------------- Main UI -------------- */
+  /*----------------------------------------*/
+
+  return (
+    <div className="dropdown" ref={dropdownRef}>
+      <button
+        className={
+          combineClassNames([
+            'btn dropdown-toggle border',
+            isDropdownOpen && 'show',
+            `btn-${variant}`,
+            variant === Variant.Light && 'text-dark',
+          ])
+        }
+        type="button"
+        id={dropdownButton.id}
+        aria-expanded={isDropdownOpen}
+        aria-label={dropdownButton.ariaLabel}
+        onClick={() => {
+          dispatch({
+            type: ActionType.ToggleDropdown,
+          });
+        }}
+      >
+        {
+          dropdownButton.content
+        }
+      </button>
+      <ul className={
+        combineClassNames([
+          'dropdown-menu',
+          `dropdown-menu-${variant}`,
+          isDropdownOpen && 'show',
+        ])
+      }
+      >
+        {Object.values(items).map((item) => {
+          if (item.type === DropdownItemType.Header) {
+            return (
+              // TODO: Implement header
+              <span />
+            );
+          }
+          if (item.type === DropdownItemType.Divider) {
+            return (
+              // TODO: Implement divider
+              <span />
+            );
+          }
+          return (
+            <li
+              key={item.id}
+            >
+              <button
+                type="button"
+                aria-label={item.ariaLabel}
+                className="dropdown-item"
+                onClick={(e) => {
+                  e.preventDefault();
+                  dispatch({
+                    type: ActionType.CloseDropdown,
+                  });
+                  item.onClick();
+                }}
+              >
+                {
+                  item.content
+                }
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+};
+
+/*------------------------------------------------------------------------*/
+/* ------------------------------- Wrap Up ------------------------------ */
+/*------------------------------------------------------------------------*/
+
+// Export component
+export default Dropdown;

package/src/helpers/validators/ChicagoTitleCase.test.ts

@@ -0,0 +1,85 @@
+// Importing the testing function
+// import chicagoTitleCase from './chicagoTitleCase';
+
+// // Import constants
+// import { INVALID_STRING_ERRORS, INVALID_REGEX_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Valid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const validTests: { input: string, expected: string }[] = [
+//   {
+//     input: 'this is the american language',
+//     expected: 'This the American language',
+//   },
+//   {
+//     input: 'to kill a mockingbird',
+//     expected: 'To Kill a Mockingbird',
+//   },
+//   {
+//     input: 'the lord of the rings',
+//     expected: 'The Lord of the Rings',
+//   },
+//   {
+//     input: 'pride and prejudice',
+//     expected: 'Pride and Prejudice',
+//   },
+//   {
+//     input: 'the road not taken',
+//     expected: 'The Road Not Taken',
+//   },
+// ];
+
+// test(
+//   'Converts strings to Chicago title case correctly.',
+//   async () => {
+//     validTests.forEach(({ input, expected }) => {
+//       expect(chicagoTitleCase(input)).toBe(expected);
+//     });
+//   },
+// );
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Edge Cases ---------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const edgeCases: { input: string, expected: string }[] = [
+//   {
+//     input: 'x',
+//     expected: 'X',
+//   },
+//   {
+//     input: ' ',
+//     expected: ' ',
+//   },
+//   {
+//     input: '',
+//     expected: '',
+//   },
+//   {
+//     input: 'the',
+//     expected: 'The',
+//   },
+//   {
+//     input: 'THE ROAD NOT TAKEN',
+//     expected: 'The Road Not Taken',
+//   },
+//   {
+//     input: 'tO kiLL A mOckingBirD',
+//     expected: 'To Kill a Mockingbird',
+//   },
+//   {
+//     input: 'pRiDe And pReduJiCe',
+//     expected: 'Pride and Prejudice',
+//   },
+// ];
+
+// test(
+//   'Handles the edge cases for the function that converts a string to Chicago Title Case.',
+//   async () => {
+//     edgeCases.forEach(({ input, expected }) => {
+//       expect(chicagoTitleCase(input)).toBe(expected);
+//     });
+//   },
+// );

package/src/helpers/validators/ChicagoTitleCase.ts

@@ -0,0 +1,32 @@
+/**
+ * This function converts a string to title case based on Chicago Title Case 
+ * Style rules.
+ * @author Leisha Bhandari
+ * @param input: The input string that needs to be converted to Chicago title
+ *               case.
+ * @returns Input string converted to title case
+ */
+
+
+const chicagoTitleCase = (input: string): string => {
+   // List of lowercase words according to Chicago Manual of Style
+  const lowerCaseWords: string[] = [
+    'in', 'nor', 'of', 'on', 'or', 'as', 'at', 'but', 'by',
+    'for', 'if', 'so', 'the', 'a', 'an', 'and', 'to', 'up',
+    'yet'
+  ];
+
+  return input
+    // Converts given input string to lowercase
+    .toLowerCase() 
+    // Splits the given string into separate words
+    .split(' ') 
+    .map((word, index, words) => 
+      // Capitalize the first word, last word, and the words that aren't
+      // in lowerCaseWords
+      index === 0 || !lowerCaseWords.includes(word) || index === words.length - 1
+        ? `${word.charAt(0).toUpperCase()}${word.slice(1)}` // Capitalize the first letter
+        : word // Nothing happens to the word
+    )
+    .join(' '); // Joins the words back 
+};

package/src/helpers/validators/findURL.test.ts

@@ -0,0 +1,83 @@
+// Import the function to be tested
+// import findURLs from './findURL';
+
+// // Import constants
+// import { INVALID_STRING_ERRORS, INVALID_REGEX_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Valid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const validTests: { block: string, expected: { start: number, end: number }[] }[] = [
+//   {
+//     block: 'Visit http://example.com for more information.',
+//     expected: [{ start: 6, end: 23 }],
+//   },
+//   {
+//     block: 'Multiple URLs: http://one.com and http://two.com.',
+//     expected: [
+//       { start: 15, end: 29 },
+//       { start: 34, end: 48 },
+//     ],
+//   },
+//   {
+//     block: 'Localhost URLs: http://localhost and http://127.0.0.1.',
+//     expected: [
+//       { start: 16, end: 31 },
+//       { start: 36, end: 52 },
+//     ],
+//   },
+//   {
+//     block: 'Embedded URL: text https://embedded-url.com?query=1&value=2.',
+//     expected: [{ start: 13, end: 51 }],
+//   },
+//   {
+//     block: 'Secure site: https://secure-site.com/path?query=string#fragment',
+//     expected: [{ start: 13, end: 58 }],
+//   },
+// ];
+
+// test(
+//   'Returns correct start and end indices for valid URLs within a string.',
+//   async () => {
+//     validTests.forEach(({ block, expected }) => {
+//       expect(findURLs(block)).toStrictEqual(expected);
+//     });
+//   },
+// );
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Invalid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const invalidTests: { block: string, expected: { start: number, end: number }[] }[] = [
+//   {
+//     block: 'No URL.',
+//     expected: [],
+//   },
+//   {
+//     block: 'URL format is wrong: http:/example.com and htt://example.com.',
+//     expected: [],
+//   },
+//   {
+//     block: 'Any punctuation after the URL http://example.com, should not count.',
+//     expected: [{ start: 20, end: 37 }],
+//   },
+//   {
+//     block: 'Starting punctuation ,http://example.com should not count.',
+//     expected: [{ start: 22, end: 39 }],
+//   },
+//   {
+//     block: 'Spaces in the middle http://exa mple.com is invalid.',
+//     expected: [],
+//   },
+// ];
+
+// test(
+//   'Returns empty array for strings without valid URLs.',
+//   async () => {
+//     invalidTests.forEach(({ block, expected }) => {
+//       expect(findURLs(block)).toStrictEqual(expected);
+//     });
+//   },
+// );

package/src/helpers/validators/findURL.ts

@@ -0,0 +1,43 @@
+// /**
+//  * This function finds URLs within a given string and returns an array of 
+//  * their locations.
+//  * @author Leisha Bhandari
+//  * @param block: The block of text to search for URLs
+//  * @returns Arrays where each of them contain the start and end index of the URL
+//  */
+// function findURLs(block: string): { start: number, end: number }[] {
+//   // Expression representing the skeleton of a URL to help match and find the  
+//   // URLs within the block of text (Also takes care of Unicode characters)
+//   const urlSkeleton = /(https?:\/\/[^\s\u0000-\u001F.,]+[^\s\u0000-\u001F.,]?(?:\?[^\s\u0000-\u001F]+)?(?:#[^\s\u0000-\u001F]+)?)/g;
+//   const found: { start: number, end: number }[] = [];
+//   let match: RegExpExecArray | null;
+
+//   // While loop to find the URLs in the given block of texts using the URL 
+//   // skeleton
+//   while ((match === urlSkeleton.exec(block)) 
+//          && match !== null) {
+//     // To find the beginning index of the URL
+//     let start = match.index;
+//     // To find the last index of the URL
+//     let end = match.index + match[0].length;
+
+//     // If statements to check whether the URL is followed by some kind of 
+//     // punctuation mark
+//     if (block.charAt(end) === '.' || /[,;:!?"]/.test(block.charAt(end))) {
+//       end--;
+//     }
+
+//     // While statement to make sure that the URL does not start with a 
+//     // punctuation mark
+//     while (start > 0 && /[.,:;!?]/.test(block.charAt(start - 1))) {
+//       start--;
+//     }
+
+//     // The object with start and end index of the URL is found and pushed to 
+//     // the found array
+//     found.push({ start, end });
+//   }
+  
+//   // Returns the array of the found URLs location
+//   return found;
+// }

package/src/helpers/validators/validURL.test.ts

@@ -0,0 +1,90 @@
+
+// Import the function to be tested
+// import isValid from './validURL';
+
+// // Import constants
+// import { INVALID_STRING_ERRORS, INVALID_REGEX_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Valid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const validUrls: string[] = [
+//   'http://example.com',
+//   'https://example.com',
+//   'http://www.example.com',
+//   'https://www.example.com',
+//   'https://example.com/path',
+//   'http://example.com/path',
+//   'https://example.com?query=string',
+//   'http://example.com?query=string',
+//   'https://example.com#fragment',
+//   'http://example.com#fragment',
+//   'http://localhost',
+//   'https://localhost:3000',
+//   'http://localhost:3000',
+//   'http://127.0.0.1',
+//   'http://127.0.0.1:3000',
+//   'ftp://example.com/path',
+//   'ftp://example.com',
+//   'https://127.0.0.1:3000',
+//   'file:///C:/path/to/file'
+// ];
+
+// test(
+//   'Returns true for a given valid URL.',
+//   async () => {
+//     validUrls.forEach((url) => {
+//       expect(isValid(url)).toBe(true);
+//     });
+//   },
+// );
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Invalid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const invalidUrls: string[] = [
+//   '',
+//   ' ',
+//   'example',
+//   'http://',
+//   'http://.',
+//   'http://..',
+//   'http://##/',
+//   'http://../',
+//   'http://??/',
+//   'http://#',
+//   'http://##',
+//   '//',
+//   '//a',
+//   '///a',
+//   '///',
+//   'http:///a',
+//   'http://www.foo.bar./',
+//   'http://foo.bar/foo(bar)baz quux',
+//   'http://3628126748',
+//   'http://.www.foo.bar/',
+//   'http://.www.foo.bar./',
+//   'http://123.123.123',
+//   'http://1.1.1.1.1',
+//   'http://example.com:99999',
+//   'http://example.com:80:80',
+//   'http://example.com::80',
+//   'http://example.com:-80',
+//   'http://-example.com',
+//   'http://example.com-',
+//   'http://example.com_',
+//   'http://example..com',
+//   'http://example.com.',
+//   'http://.example.com'
+// ];
+
+// test(
+//   'Returns false for a given invalid URL.',
+//   async () => {
+//     invalidUrls.forEach((url) => {
+//       expect(isValid(url)).toBe(false);
+//     });
+//   },
+// );

package/src/helpers/validators/validURL.ts

@@ -0,0 +1,18 @@
+/**
+ * This function checks if a given input string is a valid URL.
+ * @author Leisha Bhandari
+ * @param URL: The input string that needs checked as a URL or not.
+ * @returns A true boolean value if the input string is a valid URL, and a false
+ *          boolean value if the input string is a invalid URL
+ */
+function isValid(url: string): boolean {
+  // Uses the input URL to create a URL object
+  try {
+    new URL(url);
+    // URL constructor does not throw an error, so input URL is valid
+    return true;
+  } catch (err) {
+    // URL constructor throws an error, so input URL is invalid
+    return false;
+  }
+}

package/src/types/DropdownItemType.ts

@@ -0,0 +1,11 @@
+// Types of dropdown items
+enum DropdownItemType {
+  // Dropdown header
+  Header = 'Header',
+  // Dropdown divider
+  Divider = 'Divider',
+  // Dropdown item
+  Item = 'Item',
+}
+
+export default DropdownItemType;