dce-reactkit 3.1.2 → 3.1.5

package/dist/index.d.ts

@@ -7,7 +7,7 @@ import React from 'react';
  * @author Gabe Abrams
  */
 
-declare type Props$c = {
+declare type Props$d = {
     children: React.ReactNode;
     sendRequest: SendRequestFunction;
     dark?: boolean;
@@ -52,7 +52,7 @@ declare const confirm: (title: string, text: string) => Promise<boolean>;
  * @param [errorTitle] title of the error box
  */
 declare const showFatalError: (error: any, errorTitle?: string) => undefined;
-declare const AppWrapper: React.FC<Props$c>;
+declare const AppWrapper: React.FC<Props$d>;
 
 /**
  * Loading spinner/indicator
@@ -65,12 +65,12 @@ declare const LoadingSpinner: () => JSX.Element;
  * @author Gabe Abrams
  */
 
-declare type Props$b = {
+declare type Props$c = {
     error: any;
     title?: string;
     onClose?: () => void;
 };
-declare const ErrorBox: React.FC<Props$b>;
+declare const ErrorBox: React.FC<Props$c>;
 
 /**
  * Bootstrap variants
@@ -136,7 +136,7 @@ declare enum ModalType {
  * @author Gabe Abrams
  */
 
-declare type Props$a = {
+declare type Props$b = {
     type?: ModalType;
     size?: ModalSize;
     title?: React.ReactNode;
@@ -165,27 +165,27 @@ declare type Props$a = {
     confirmVariant?: Variant;
     onTopOfOtherModals?: boolean;
 };
-declare const Modal: React.FC<Props$a>;
+declare const Modal: React.FC<Props$b>;
 
 /**
  * A box with a tab on the top that holds buttons and other content
  * @author Gabe Abrams
  */
 
-declare type Props$9 = {
+declare type Props$a = {
     title: React.ReactNode;
     children: React.ReactNode;
     noBottomMargin?: boolean;
     noBottomPadding?: boolean;
 };
-declare const TabBox: React.FC<Props$9>;
+declare const TabBox: React.FC<Props$a>;
 
 /**
  * A radio selection button
  * @author Gabe Abrams
  */
 
-declare type Props$8 = {
+declare type Props$9 = {
     text: string;
     onSelected: () => void;
     ariaLabel: string;
@@ -197,46 +197,47 @@ declare type Props$8 = {
     unselectedVariant?: Variant;
     small?: boolean;
 };
-declare const RadioButton: React.FC<Props$8>;
+declare const RadioButton: React.FC<Props$9>;
 
 /**
  * A checkbox button
  * @author Gabe Abrams
  */
 
-declare type Props$7 = {
+declare type Props$8 = {
     text: string;
     onChanged: (checked: boolean) => void;
     ariaLabel: string;
     title?: string;
     checked?: boolean;
     id?: string;
+    className?: string;
     noMarginOnRight?: boolean;
     checkedVariant?: Variant;
     uncheckedVariant?: Variant;
     small?: boolean;
     dashed?: boolean;
 };
-declare const CheckboxButton: React.FC<Props$7>;
+declare const CheckboxButton: React.FC<Props$8>;
 
 /**
  * Input group with a title and space for buttons
  * @author Gabe Abrams
  */
 
-declare type Props$6 = {
+declare type Props$7 = {
     label: string;
     minLabelWidth?: string;
     children: React.ReactNode;
 };
-declare const ButtonInputGroup: React.FC<Props$6>;
+declare const ButtonInputGroup: React.FC<Props$7>;
 
 /**
  * A very simple, lightweight date chooser
  * @author Gabe Abrams
  */
 
-declare type Props$5 = {
+declare type Props$6 = {
     ariaLabel: string;
     name: string;
     month: number;
@@ -251,60 +252,60 @@ declare type Props$5 = {
     onChange: (month: number, day: number, year: number) => void;
     numMonthsToShow?: number;
 };
-declare const SimpleDateChooser: React.FC<Props$5>;
+declare const SimpleDateChooser: React.FC<Props$6>;
 
 /**
  * Drawer container
  * @author Gabe Abrams
  */
 
-declare type Props$4 = {
+declare type Props$5 = {
     children: React.ReactNode;
 };
-declare const Drawer: React.FC<Props$4>;
+declare const Drawer: React.FC<Props$5>;
 
 /**
  * Success checkmark that pops into view
  * @author Gabe Abrams
  */
 
-declare type Props$3 = {
+declare type Props$4 = {
     sizeRem?: number;
     circleVariant?: string;
     checkVariant?: string;
 };
-declare const PopSuccessMark: React.FC<Props$3>;
+declare const PopSuccessMark: React.FC<Props$4>;
 
 /**
  * Failure x mark that pops into view
  * @author Gabe Abrams
  */
 
-declare type Props$2 = {
+declare type Props$3 = {
     sizeRem?: number;
     circleVariant?: string;
     xVariant?: string;
 };
-declare const PopFailureMark: React.FC<Props$2>;
+declare const PopFailureMark: React.FC<Props$3>;
 
 /**
  * Failure pending that pops into view
  * @author Gabe Abrams
  */
 
-declare type Props$1 = {
+declare type Props$2 = {
     sizeRem?: number;
     circleVariant?: string;
     hourglassVariant?: string;
 };
-declare const PopPendingMark: React.FC<Props$1>;
+declare const PopPendingMark: React.FC<Props$2>;
 
 /**
  * Copiable text box
  * @author Gabe Abrams
  */
 
-declare type Props = {
+declare type Props$1 = {
     text: string;
     maxTextWidthRem?: number;
     label: string;
@@ -316,7 +317,40 @@ declare type Props = {
     textAreaId?: string;
     copyButtonId?: string;
 };
-declare const CopiableBox: React.FC<Props>;
+declare const CopiableBox: React.FC<Props$1>;
+
+/**
+ * An item that can be chosen (for use within ItemPicker)
+ * @author Gabe Abrams
+ */
+declare type PickableItem = ({
+    id: number | string;
+    name: string;
+    link?: string;
+} & ({
+    isGroup: false;
+    checked: boolean;
+} | {
+    isGroup: true;
+    children: PickableItem[];
+}));
+
+/**
+ * Reusable nested item picker
+ * @author Yuen Ler Chow
+ */
+
+declare type Props = {
+    title: string;
+    items: PickableItem[];
+    /**
+     * Handler to call when item selection is changed
+     * @param updatedItems an updated copy of the list of items with checked
+     *   values updated
+     */
+    onChanged: (updatedItems: PickableItem[]) => void;
+};
+declare const ItemPicker: React.FC<Props>;
 
 /**
  * An error with a code
@@ -613,6 +647,14 @@ declare const getPartOfDay: () => string;
  */
 declare const stringsToHumanReadableList: (items: string[]) => string;
 
+/**
+ * Given a string, only keep the letters inside it
+ * @author Gabe Abrams
+ * @param str the string to parse
+ * @returns only the letters inside of the string
+ */
+declare const onlyKeepLetters: (str: string) => string;
+
 /**
  * List of error codes built into the react kit
  * @author Gabe Abrams
@@ -644,4 +686,4 @@ declare enum DayOfWeek {
     Sunday = "u"
 }
 
-export { AppWrapper, ButtonInputGroup, CheckboxButton, CopiableBox, DAY_IN_MS, DayOfWeek, Drawer, ErrorBox, ErrorWithCode, HOUR_IN_MS, LoadingSpinner, MINUTE_IN_MS, Modal, ModalButtonType, ModalSize, ModalType, ParamType, PopFailureMark, PopPendingMark, PopSuccessMark, RadioButton, ReactKitErrorCode, SimpleDateChooser, TabBox, Variant, abbreviate, alert, avg, ceilToNumDecimals, confirm, floorToNumDecimals, forceNumIntoBounds, genRouteHandler, getHumanReadableDate, getOrdinal, getPartOfDay, getTimeInfoInET, handleError, handleSuccess, initServer, padDecimalZeros, padZerosLeft, roundToNumDecimals, showFatalError, startMinWait, stringsToHumanReadableList, stubServerEndpoint, sum, visitServerEndpoint, waitMs };
+export { AppWrapper, ButtonInputGroup, CheckboxButton, CopiableBox, DAY_IN_MS, DayOfWeek, Drawer, ErrorBox, ErrorWithCode, HOUR_IN_MS, ItemPicker, LoadingSpinner, MINUTE_IN_MS, Modal, ModalButtonType, ModalSize, ModalType, ParamType, PopFailureMark, PopPendingMark, PopSuccessMark, RadioButton, ReactKitErrorCode, SimpleDateChooser, TabBox, Variant, abbreviate, alert, avg, ceilToNumDecimals, confirm, floorToNumDecimals, forceNumIntoBounds, genRouteHandler, getHumanReadableDate, getOrdinal, getPartOfDay, getTimeInfoInET, handleError, handleSuccess, initServer, onlyKeepLetters, padDecimalZeros, padZerosLeft, roundToNumDecimals, showFatalError, startMinWait, stringsToHumanReadableList, stubServerEndpoint, sum, visitServerEndpoint, waitMs };

package/package.json

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

package/src/components/CheckboxButton.tsx

@@ -31,6 +31,8 @@ type Props = {
   checked?: boolean,
   // The id of the button
   id?: string,
+  // Custom class name of the button
+  className?: string,
   // If true, no margin on right
   noMarginOnRight?: boolean,
   // Variant for when checkbox is checked
@@ -61,6 +63,7 @@ const CheckboxButton: React.FC<Props> = (props) => {
     title,
     checked,
     id,
+    className,
     noMarginOnRight,
     checkedVariant = Variant.Secondary,
     uncheckedVariant = Variant.Light,
@@ -94,7 +97,7 @@ const CheckboxButton: React.FC<Props> = (props) => {
       type="button"
       id={id}
       title={title}
-      className={`CheckboxButton-status-${checked ? 'checked' : 'unchecked'} ${dashed ? 'CheckboxButton-dashed ' : ''}btn btn-${checked ? checkedVariant : uncheckedVariant}${checked ? ' selected' : ''}${small ? ' btn-sm' : ''} m-0${noMarginOnRight ? '' : ' me-1'}`}
+      className={`CheckboxButton-status-${checked ? 'checked' : 'unchecked'} ${dashed ? 'CheckboxButton-dashed ' : ''}btn btn-${checked ? checkedVariant : uncheckedVariant}${checked ? ' selected' : ''}${small ? ' btn-sm' : ''} m-0${noMarginOnRight ? '' : ' me-1'} ${className ?? ''}`}
       aria-label={`${ariaLabel}${checked ? ': currently checked' : ''}`}
       onClick={() => {
         onChanged(!checked);

package/src/components/ItemPicker/NestableItemList.tsx

@@ -0,0 +1,288 @@
+/**
+ * Reusable nested item picker
+ * @author Yuen Ler Chow
+ */
+
+// Import React
+import React, { useReducer } from 'react';
+
+// Import FontAwesome
+import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
+import {
+  faChevronRight,
+  faChevronDown,
+} from '@fortawesome/free-solid-svg-icons';
+
+// Import shared components
+import CheckboxButton from '../CheckboxButton';
+import Variant from '../../types/Variant';
+
+// Import types
+import PickableItem from './types/PickableItem';
+
+/*------------------------------------------------------------------------*/
+/*                                  Types                                 */
+/*------------------------------------------------------------------------*/
+
+// Props definition
+type Props = {
+  // List of items to show
+  items: PickableItem[],
+  /**
+   * Handler to call when item selection is changed
+   * @param updatedItems an updated copy of the list of items with checked
+   *   values updated
+   */
+  onChanged: (updatedItems: PickableItem[]) => void,
+};
+
+/*------------------------------------------------------------------------*/
+/*                                  State                                 */
+/*------------------------------------------------------------------------*/
+
+/* -------- State Definition -------- */
+
+type State = {
+  // True if children are being shown
+  isShowingItems: boolean,
+};
+
+/* ------------- Actions ------------ */
+
+// Types of actions
+enum ActionType {
+  // Toggle whether the children are being shown
+  ToggleItems = 'toggle-items',
+}
+
+// Action definitions
+type Action = (
+  | {
+    // Action type
+    type: ActionType.ToggleItems,
+  }
+);
+
+/**
+ * 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.ToggleItems: {
+      return { isShowingItems: !state.isShowingItems };
+    }
+    default: {
+      return state;
+    }
+  }
+};
+
+/*------------------------------------------------------------------------*/
+/*                                Component                               */
+/*------------------------------------------------------------------------*/
+
+const NestableItemList: React.FC<Props> = (props) => {
+  /*------------------------------------------------------------------------*/
+  /*                                  Setup                                 */
+  /*------------------------------------------------------------------------*/
+
+  /* -------------- Props ------------- */
+
+  // Destructure all props
+  const {
+    items,
+    onChanged,
+  } = props;
+
+  /* -------------- State ------------- */
+
+  // Initial state
+  const initialState: State = {
+    isShowingItems: true,
+  };
+
+  // Initialize state
+  const [state, dispatch] = useReducer(reducer, initialState);
+
+  // Destructure common state
+  const {
+    isShowingItems,
+  } = state;
+
+  /*------------------------------------------------------------------------*/
+  /*                           Component Functions                          */
+  /*------------------------------------------------------------------------*/
+
+  /**
+   * Checks if all items in a list are checked
+   * @author Yuen Ler Chow
+   * @param pickableItems a list of items
+   * @returns true if all items are checked. If any item is a group,
+   *   we recursively check its children
+   */
+  const allChecked = (pickableItems: PickableItem[]): boolean => {
+    return pickableItems.every((item: PickableItem) => {
+      if (item.isGroup) {
+        return allChecked(item.children);
+      }
+      return item.checked;
+    });
+  };
+
+  /**
+   * Checks if none of the items in a list are checked
+   * @author Yuen Ler Chow
+   * @param pickableItems a list of items
+   * @returns true if all items are unchecked. If any item is a group, we
+   *   recursively check its children
+   */
+  const noneChecked = (pickableItems: PickableItem[]): boolean => {
+    return pickableItems.every((item: PickableItem) => {
+      if (item.isGroup) {
+        return noneChecked(item.children);
+      }
+      return !item.checked;
+    });
+  };
+
+  /**
+   * Change whether specific items are checked
+   * @author Yuen Ler Chow
+   * @param id the id of the item we want to check or uncheck OR true if
+   *   we are checking/unchecking all items, independent of their id
+   * @param checked if true, the item will be checked.
+   * @param pickableItems the list of items we iterate through to find the item
+   *   we want to check/uncheck
+   * @returns a list of items with the item now checked/unchecked.
+   *   If it is a group, its children will also become checked/unchecked
+   */
+  const changeChecked = (id: string | number | true, checked: boolean, pickableItems: PickableItem[]): PickableItem[] => {
+    const updatedItems: PickableItem[] = pickableItems.map((item: PickableItem) => {
+      if (item.id === id || id === true) {
+        if (item.isGroup) {
+          return {
+            ...item,
+            children: changeChecked(true, checked, item.children),
+          };
+        }
+        return {
+          ...item,
+          checked,
+        };
+      }
+      if (item.isGroup) {
+        return {
+          ...item,
+          children: changeChecked(id, checked, item.children),
+        };
+      }
+      return item;
+    });
+    return updatedItems;
+  };
+
+  /**
+   * Within a tree of items, swap in the list of updated items into the spot
+   *   indicated by the id
+   * @author Yuen Ler Chow
+   * @param id the id of the item group we want to change
+   * @param updatedItems the list of items we want to change the items in the group to
+   * @returns a list of all items containing the updated items
+   */
+  const changeItems = (id: string | number, updatedItems: PickableItem[]): PickableItem[] => {
+    return items.map((item: PickableItem) => {
+      if (item.id === id) {
+        return {
+          ...item,
+          children: updatedItems,
+        };
+      }
+      return item;
+    });
+  };
+
+  /*------------------------------------------------------------------------*/
+  /*                                 Render                                 */
+  /*------------------------------------------------------------------------*/
+
+  return (
+    <div>
+      {
+        items.map((item) => {
+          return (
+            <div key={item.id}>
+              {/* Dropdown Button */}
+              <span
+                className="NestableItemList-dropdown-button-container d-inline-block"
+                style={{
+                  minWidth: '2rem',
+                }}
+              >
+                {item.isGroup && (
+                  <button
+                    className={`NestableItemList-dropdown-button NestableItemList-dropdown-button-${item.id}`}
+                    style={{
+                      border: 0,
+                      backgroundColor: 'transparent',
+                    }}
+                    type="button"
+                    onClick={() => {
+                      dispatch({
+                        type: ActionType.ToggleItems,
+                      });
+                    }}
+                    aria-label={`${isShowingItems ? 'Hide' : 'Show'} items in ${item.name}`}
+                  >
+                    <FontAwesomeIcon
+                      icon={isShowingItems ? faChevronDown : faChevronRight}
+                    />
+                  </button>
+                )}
+              </span>
+
+              {/* Checkbox and Text */}
+              <CheckboxButton
+                className={`NestableItemList-CheckboxButton-${item.id}`}
+                text={item.name}
+                checked={item.isGroup ? allChecked(item.children) : item.checked}
+                dashed={item.isGroup ? !noneChecked(item.children) : false}
+                onChanged={(checked) => {
+                  onChanged(changeChecked(item.id, checked, items));
+                }}
+                ariaLabel={`Select ${item.name}`}
+                checkedVariant={Variant.Light}
+              />
+
+              {/* Children */}
+              {item.isGroup && isShowingItems && (
+                <div
+                  className="NestableItemList-children-container"
+                  style={{
+                    paddingLeft: '2.2rem',
+                  }}
+                >
+                  <NestableItemList
+                    items={item.children}
+                    onChanged={(updatedItems) => {
+                      onChanged(changeItems(item.id, updatedItems));
+                    }}
+                  />
+                </div>
+              )}
+            </div>
+          );
+        })
+      }
+    </div>
+  );
+};
+
+/*------------------------------------------------------------------------*/
+/*                                 Wrap Up                                */
+/*------------------------------------------------------------------------*/
+
+// Export component
+export default NestableItemList;

package/src/components/ItemPicker/index.tsx

@@ -0,0 +1,85 @@
+/**
+ * Reusable nested item picker
+ * @author Yuen Ler Chow
+ */
+
+// Import React
+import React from 'react';
+
+// Import shared components
+import TabBox from '../TabBox';
+
+// Import types
+import PickableItem from './types/PickableItem';
+
+// Import sub-components
+import NestableItemList from './NestableItemList';
+
+/*------------------------------------------------------------------------*/
+/*                                  Types                                 */
+/*------------------------------------------------------------------------*/
+
+// Props definition
+type Props = {
+  // Title of the picker
+  title: string,
+  // List of items to show
+  items: PickableItem[],
+  /**
+   * Handler to call when item selection is changed
+   * @param updatedItems an updated copy of the list of items with checked
+   *   values updated
+   */
+  onChanged: (updatedItems: PickableItem[]) => void,
+};
+
+/*------------------------------------------------------------------------*/
+/*                                Component                               */
+/*------------------------------------------------------------------------*/
+
+const ItemPicker: React.FC<Props> = (props) => {
+  /*------------------------------------------------------------------------*/
+  /*                                  Setup                                 */
+  /*------------------------------------------------------------------------*/
+
+  /* -------------- Props ------------- */
+
+  // Destructure all props
+  const {
+    title,
+    items,
+    onChanged,
+  } = props;
+
+  /*------------------------------------------------------------------------*/
+  /*                           Component Functions                          */
+  /*------------------------------------------------------------------------*/
+
+  /*------------------------------------------------------------------------*/
+  /*                                 Render                                 */
+  /*------------------------------------------------------------------------*/
+
+  /*----------------------------------------*/
+  /*                 Main UI                */
+  /*----------------------------------------*/
+
+  return (
+    <TabBox
+      title={title}
+    >
+      <div style={{ overflowX: 'scroll' }}>
+        <NestableItemList
+          items={items}
+          onChanged={onChanged}
+        />
+      </div>
+    </TabBox>
+  );
+};
+
+/*------------------------------------------------------------------------*/
+/*                                 Wrap Up                                */
+/*------------------------------------------------------------------------*/
+
+// Export component
+export default ItemPicker;

package/src/components/ItemPicker/types/PickableItem.tsx

@@ -0,0 +1,30 @@
+/**
+ * An item that can be chosen (for use within ItemPicker)
+ * @author Gabe Abrams
+ */
+type PickableItem = (
+  {
+    // Unique id of the item
+    id: number | string,
+    // Name of the item (human readable)
+    name: string,
+    // Link to view the item in the browser
+    link?: string,
+  }
+  & (
+    | {
+      // True if this is a group of items
+      isGroup: false,
+      // True if item is checked
+      checked: boolean,
+    }
+    | {
+      // True if this is a group of items
+      isGroup: true,
+      // List of sub-items
+      children: PickableItem[],
+    }
+  )
+);
+
+export default PickableItem;