@performant-software/semantic-components 1.0.17 → 1.0.18-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@performant-software/semantic-components",
-  "version": "1.0.17",
+  "version": "1.0.18-beta.0",
   "description": "A package of shared components based on the Semantic UI Framework.",
   "license": "MIT",
   "main": "./build/index.js",
@@ -12,7 +12,7 @@
     "build": "webpack --mode production && flow-copy-source -v src types"
   },
   "dependencies": {
-    "@performant-software/shared-components": "^1.0.17",
+    "@performant-software/shared-components": "^1.0.18-beta.0",
     "@react-google-maps/api": "^2.8.1",
     "axios": "^0.26.1",
     "i18next": "^19.4.4",
@@ -32,8 +32,8 @@
     "zotero-translation-client": "^5.0.1"
   },
   "peerDependencies": {
-    "react": ">= 16.13.1 < 18.0.0",
-    "react-dom": ">= 16.13.1 < 18.0.0"
+    "react": ">= 16.13.1 < 19.0.0",
+    "react-dom": ">= 16.13.1 < 19.0.0"
   },
   "devDependencies": {
     "@performant-software/webpack-config": "^1.0.0",
@@ -41,7 +41,7 @@
     "less": "^4.1.2",
     "less-loader": "^11.0.0",
     "mini-css-extract-plugin": "^2.6.0",
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
   }
 }

package/src/components/BibliographyForm.js

@@ -0,0 +1,121 @@
+// @flow
+
+import type { EditContainerProps } from '@performant-software/shared-components/types';
+import React, { useCallback, useEffect, useState } from 'react';
+import { Form } from 'semantic-ui-react';
+import _ from 'underscore';
+import BibliographyUtils from '../utils/Bibliography';
+import Creators from './Creators';
+
+type Props = EditContainerProps & {
+  /**
+   * A JSON representation of the bibliographic item.
+   */
+  item: any
+};
+
+// Field constants
+const FIELD_ABSTRACT_NOTE = 'abstractNote';
+const FIELD_CREATORS = 'creators';
+const FIELD_EXTRA = 'extra';
+const FIELD_ITEM_TYPE = 'itemType';
+
+/**
+ * This component can be used in conjunction with the `useEditContainer` higher-order component to create a form
+ * used to enter bibliographic data.
+ */
+const BibliographyForm = (props: Props) => {
+  const [creators, setCreators] = useState([]);
+  const [fields, setFields] = useState([]);
+
+  /**
+   * Renders the input element for the passed field.
+   *
+   * @type {(function(*): *)|*}
+   */
+  const renderField = useCallback((field) => {
+    if (field.key === FIELD_ITEM_TYPE) {
+      return (
+        <Form.Dropdown
+          disabled={field.readonly}
+          key={field.key}
+          label={field.label}
+          onChange={props.onTextInputChange.bind(this, field.key)}
+          options={_.map(field.options, (option) => ({
+            key: option.value,
+            value: option.value,
+            text: option.label
+          }))}
+          selectOnBlur={false}
+          selection
+          value={props.item[field.key] || ''}
+        />
+      );
+    }
+
+    if (field.key === FIELD_CREATORS) {
+      return (
+        <Creators
+          creatorTypes={creators}
+          key={field.key}
+          onChange={(value) => props.onSetState({ [field.key]: value })}
+          value={props.item[field.key] || []}
+        />
+      );
+    }
+
+    if (field.key === FIELD_ABSTRACT_NOTE || field.key === FIELD_EXTRA) {
+      return (
+        <Form.TextArea
+          disabled={field.readonly}
+          key={field.key}
+          label={field.label}
+          onChange={props.onTextInputChange.bind(this, field.key)}
+          value={props.item[field.key] || ''}
+        />
+      );
+    }
+
+    return (
+      <Form.Input
+        disabled={field.readonly}
+        key={field.key}
+        label={field.label}
+        onChange={props.onTextInputChange.bind(this, field.key)}
+        value={props.item[field.key] || ''}
+      />
+    );
+  }, [creators, props.item]);
+
+  /**
+   * Load the metadata for the selected item type.
+   */
+  useEffect(() => {
+    BibliographyUtils
+      .getItemTypeMeta(props.item.itemType)
+      .then((data) => {
+        const itemTypes = _.map(data.itemTypes, (it) => ({
+          value: it.itemType,
+          label: it.localized
+        }));
+
+        const itemTypeCreatorTypes = _.map(data.itemTypeCreatorTypes, (ct) => ({
+          value: ct.creatorType,
+          label: ct.localized
+        }));
+
+        setCreators(itemTypeCreatorTypes);
+
+        const bibliographyData = BibliographyUtils.getFieldsAndItem(props.item, data.itemTypeFields, itemTypes);
+        setFields(bibliographyData.fields);
+      });
+  }, [props.item.itemType]);
+
+  return (
+    <>
+      { _.map(fields, renderField) }
+    </>
+  );
+};
+
+export default BibliographyForm;

package/src/components/BibliographyList.js

@@ -23,7 +23,7 @@ import SortSelector from './SortSelector';
 import { SORT_DESCENDING } from '../constants/Sort';
 import StyleSelector from './StyleSelector';
 import Toaster from './Toaster';
-import useList from './List';
+import useList, { Props as ListProps } from './List';
 import ZoteroTranslateContext from '../context/ZoteroTranslateContext';
 import './BibliographyList.css';
 
@@ -110,13 +110,32 @@ const BibliographyListComponent: ComponentType<any> = useList((props: ComponentP
   </List>
 ));
 
-type Props = {
+type Props = ListProps & {
+  /**
+   * The array of bibliography items.
+   */
   items: Array<Item>,
+
+  /**
+   * Callback fired when the passed item is deleted. This function should return a Promise.
+   */
   onDelete: (item: Item) => Promise<any>,
+
+  /**
+   * Callback fired when the passed item is saved. This function should return a Promise.
+   */
   onSave: (item: Item) => Promise<any>,
+
+  /**
+   * URL of the Zotero translation server.
+   */
   translateUrl: string
 };
 
+/**
+ * This component renders a list of bibliography items in Zbib format. This component requires the URL of a running
+ * [Zotero Translation Server](https://github.com/zotero/translation-server) to be passed as the `translateUrl` prop.
+ */
 const BibliographyList = (props: Props) => {
   const [locale, setLocale] = useState();
   const [showToaster, setShowToaster] = useState(false);

package/src/components/BibliographyModal.js

@@ -1,125 +1,31 @@
 // @flow
 
 import type { EditContainerProps } from '@performant-software/shared-components/types';
-import React, { useCallback, useEffect, useState } from 'react';
+import React from 'react';
 import { Form, Modal } from 'semantic-ui-react';
-import _ from 'underscore';
-import BibliographyUtils from '../utils/Bibliography';
-import Creators from './Creators';
 import i18n from '../i18n/i18n';
+import BibliographyForm from './BibliographyForm';
 
 type Props = EditContainerProps & {
   item: any
 };
 
-// Field constants
-const FIELD_ABSTRACT_NOTE = 'abstractNote';
-const FIELD_CREATORS = 'creators';
-const FIELD_EXTRA = 'extra';
-const FIELD_ITEM_TYPE = 'itemType';
-
-const BibliographyModal = (props: Props) => {
-  const [creators, setCreators] = useState([]);
-  const [fields, setFields] = useState([]);
-
-  /**
-   * Renders the input element for the passed field.
-   *
-   * @type {(function(*): *)|*}
-   */
-  const renderField = useCallback((field) => {
-    if (field.key === FIELD_ITEM_TYPE) {
-      return (
-        <Form.Dropdown
-          disabled={field.readonly}
-          key={field.key}
-          label={field.label}
-          onChange={props.onTextInputChange.bind(this, field.key)}
-          options={_.map(field.options, (option) => ({
-            key: option.value,
-            value: option.value,
-            text: option.label
-          }))}
-          selectOnBlur={false}
-          selection
-          value={props.item[field.key] || ''}
-        />
-      );
-    }
-
-    if (field.key === FIELD_CREATORS) {
-      return (
-        <Creators
-          creatorTypes={creators}
-          key={field.key}
-          onChange={(value) => props.onSetState({ [field.key]: value })}
-          value={props.item[field.key] || []}
-        />
-      );
-    }
-
-    if (field.key === FIELD_ABSTRACT_NOTE || field.key === FIELD_EXTRA) {
-      return (
-        <Form.TextArea
-          disabled={field.readonly}
-          key={field.key}
-          label={field.label}
-          onChange={props.onTextInputChange.bind(this, field.key)}
-          value={props.item[field.key] || ''}
-        />
-      );
-    }
-
-    return (
-      <Form.Input
-        disabled={field.readonly}
-        key={field.key}
-        label={field.label}
-        onChange={props.onTextInputChange.bind(this, field.key)}
-        value={props.item[field.key] || ''}
-      />
-    );
-  }, [creators, props.item]);
-
-  /**
-   * Load the metadata for the selected item type.
-   */
-  useEffect(() => {
-    BibliographyUtils
-      .getItemTypeMeta(props.item.itemType)
-      .then((data) => {
-        const itemTypes = _.map(data.itemTypes, (it) => ({
-          value: it.itemType,
-          label: it.localized
-        }));
-
-        const itemTypeCreatorTypes = _.map(data.itemTypeCreatorTypes, (ct) => ({
-          value: ct.creatorType,
-          label: ct.localized
-        }));
-
-        setCreators(itemTypeCreatorTypes);
-
-        const bibliographyData = BibliographyUtils.getFieldsAndItem(props.item, data.itemTypeFields, itemTypes);
-        setFields(bibliographyData.fields);
-      });
-  }, [props.item.itemType]);
-
-  return (
-    <Modal
-      as={Form}
-      centered={false}
-      open
-    >
-      <Modal.Header
-        content={i18n.t('BibliographyModal.title')}
+const BibliographyModal = (props: Props) => (
+  <Modal
+    as={Form}
+    centered={false}
+    open
+  >
+    <Modal.Header
+      content={i18n.t('BibliographyModal.title')}
+    />
+    <Modal.Content>
+      <BibliographyForm
+        {...props}
       />
-      <Modal.Content>
-        { _.map(fields, renderField) }
-      </Modal.Content>
-      { props.children }
-    </Modal>
-  );
-};
+    </Modal.Content>
+    { props.children }
+  </Modal>
+);
 
 export default BibliographyModal;

package/src/components/BibliographySearchInput.js

@@ -9,10 +9,23 @@ import ZoteroTranslateContext from '../context/ZoteroTranslateContext';
 import './BibliographySearchInput.css';
 
 type Props = {
+  /**
+   * Callback fired when the translator encounters an error.
+   */
   onError: () => void,
+
+  /**
+   * Callback fired when the translator is successful.
+   * @param items
+   */
   onFind: (items: array<any>) => void
 };
 
+/**
+ * This component renders a search input and can be used within a `ZoteroTranslateContext` to lookup sources by URL,
+ * ISBN, DOI, and more identifiers. The `ZoteroTranslateContext` requires a running
+ * [Zotero Translation Server](https://github.com/zotero/translation-server) to be passed as the `translateUrl` key.
+ */
 const BibliographySearchInput = (props: Props) => {
   const [loading, setLoading] = useState(false);
   const [searchQuery, setSearchQuery] = useState('');

package/src/components/CurrentFacetLabels.js

@@ -15,6 +15,10 @@ type Props = {
   onShowMore?: () => void
 };
 
+/**
+ * This component displays the passed items as labels. If a <code>count</code> prop is provided, the component
+ * will display a "+" button.
+ */
 const CurrentFacetLabels = (props: Props) => (
   <Label.Group>
     { _.map(props.items, (item, index) => (

package/src/components/CurrentFacets.js

@@ -7,9 +7,15 @@ import CurrentFacetsModal from './CurrentFacetsModal';
 import { type CurrentRefinementsProps } from '../types/InstantSearch';
 
 type Props = CurrentRefinementsProps & {
+  /**
+   * The maximum number of facets to display. If more facets are added, they will be accessible via modal.
+   */
   limit?: number
 };
 
+/**
+ * This component can be used to display the facets/refinements currently applied to an InstantSearch index.
+ */
 const CurrentFacets = ({ useCurrentRefinements, ...props }: Props) => {
   const [modal, setModal] = useState(false);
   const { items } = useCurrentRefinements(props);

package/src/components/CurrentFacetsModal.js

@@ -6,11 +6,25 @@ import CurrentFacetLabels, { type Item } from './CurrentFacetLabels';
 import i18n from '../i18n/i18n';
 
 type Props = {
+  /**
+   * An array of facet values.
+   */
   items: Array<Item>,
+
+  /**
+   * Callback fired when the "Done" button is clicked.
+   */
   onClose: () => void,
+
+  /**
+   * If `true` the modal will be visible.
+   */
   open?: boolean
 };
 
+/**
+ * This component displays all of the facets currently applied, without any limit.
+ */
 const CurrentFacetsModal = (props: Props) => (
   <Modal
     centered={false}

package/src/components/Facet.js

@@ -10,12 +10,30 @@ import {
 import './Facet.css';
 
 type Props = {
-  children?: Node,
+  /**
+   * Facet content to display inside the accordion menu.
+   */
+  children: Node,
+
+  /**
+   * If `true`, the facet will be expanded by default.
+   */
   defaultActive?: boolean,
+
+  /**
+   * If `true`, a divider will be rendered between each facet in the list.
+   */
   divided?: boolean,
+
+  /**
+   * Facet title to display at the top.
+   */
   title: string
 };
 
+/**
+ * This component can be used as a wrapper to display various types of facets (list, toggle, etc).
+ */
 const Facet = (props: Props) => {
   const [active, setActive] = useState(props.defaultActive);
 

package/src/components/FacetClearButton.js

@@ -1,11 +1,15 @@
 // @flow
 
 import React from 'react';
-import { Button, ButtonProps } from 'semantic-ui-react';
+import { Button, type ButtonProps } from 'semantic-ui-react';
 import { type ClearRefinementsProps } from '../types/InstantSearch';
 
-type Props = typeof ButtonProps & ClearRefinementsProps;
+type Props = ButtonProps & ClearRefinementsProps;
 
+/**
+ * This component is used with the `useClearRefinements` hook from Instant Search Hooks. This component also accepts
+ * all of the props of the Semantic UI <code>Button</code> component.
+ */
 const FacetClearButton = ({ useClearRefinements, ...props }: Props) => {
   const { refine, canRefine } = useClearRefinements(props);
 

package/src/components/FacetList.js

@@ -21,11 +21,37 @@ import LinkButton from './LinkButton';
 import { type RefinementListProps } from '../types/InstantSearch';
 
 type Props = FacetProps & RefinementListProps & {
+  /**
+   * The default value for the `operator` prop. If not provided, this will default to `or`.
+   */
+  defaultOperator?: string,
+
+  /**
+   * Default value of the facet list.
+   */
   defaultValue?: string,
-  searchable?: boolean
+
+  /**
+   * If "true", the component will render a search box for searching individual facet values.
+   */
+  searchable?: boolean,
+
+  /**
+   * If "true", the component will render a toggle to change the behavior of the list from "or" to "and" logic.
+   */
+  toggleable?: boolean
 };
 
+const OPERATOR_OR = 'or';
+const OPERATOR_AND = 'and';
+
+/**
+ * This component is used with the `useRefinementList` hook from Instant Search Hooks. If the `searchable` prop
+ * is "true", the component will also render a search box used to filter the list of facet values.
+ */
 const FacetList = ({ useRefinementList, ...props }: Props) => {
+  const [operator, setOperator] = useState(props.defaultOperator || OPERATOR_OR);
+
   const {
     items,
     refine,
@@ -33,7 +59,7 @@ const FacetList = ({ useRefinementList, ...props }: Props) => {
     isShowingMore,
     searchForItems,
     toggleShowMore,
-  } = useRefinementList(props);
+  } = useRefinementList({ ...props, operator });
 
   const ref = useRef();
   const [query, setQuery] = useState('');
@@ -152,8 +178,23 @@ const FacetList = ({ useRefinementList, ...props }: Props) => {
           />
         </>
       )}
+      { props.toggleable && (
+        <Checkbox
+          checked={operator === OPERATOR_AND}
+          label={operator === OPERATOR_OR
+            ? i18n.t('FacetList.labels.matchAny')
+            : i18n.t('FacetList.labels.matchAll')}
+          onClick={() => setOperator((prevOperator) => (prevOperator === OPERATOR_OR ? OPERATOR_AND : OPERATOR_OR))}
+          toggle
+        />
+      )}
     </Facet>
   );
 };
 
+FacetList.defaultProps = {
+  ...Facet.defaultProps,
+  defaultOperator: OPERATOR_OR
+};
+
 export default FacetList;

package/src/components/FacetSlider.js

@@ -4,11 +4,15 @@ import Slider from 'rc-slider';
 import React, { useEffect, useState } from 'react';
 import { Grid } from 'semantic-ui-react';
 import Facet, { type Props as FacetProps } from './Facet';
-import { type RangerSliderProps } from '../types/InstantSearch';
+import { type RangeSliderProps } from '../types/InstantSearch';
+import 'rc-slider/assets/index.css';
 import './FacetSlider.css';
 
-type Props = FacetProps & RangerSliderProps;
+type Props = FacetProps & RangeSliderProps;
 
+/**
+ * This component can be used with the `useRange` hook from Instant Search Hooks.
+ */
 const FacetSlider = ({ useRangeSlider, ...props }: Props) => {
   const {
     start,
@@ -74,8 +78,6 @@ const FacetSlider = ({ useRangeSlider, ...props }: Props) => {
   );
 };
 
-FacetSlider.defaultProps = {
-  defaultValue: undefined
-};
+FacetSlider.defaultProps = Facet.defaultProps;
 
 export default FacetSlider;

package/src/components/FacetToggle.js

@@ -7,6 +7,9 @@ import { type ToggleRefinementProps } from '../types/InstantSearch';
 
 type Props = FacetProps & ToggleRefinementProps;
 
+/**
+ * This component is used with the `useToggleRefinement` hook from Instant Search Hooks.
+ */
 const FacetToggle = ({ useToggleRefinement, ...props }: Props) => {
   const {
     value: {
@@ -44,4 +47,6 @@ const FacetToggle = ({ useToggleRefinement, ...props }: Props) => {
   );
 };
 
+FacetToggle.defaultProps = Facet.defaultProps;
+
 export default FacetToggle;

package/src/components/SearchBox.js

@@ -2,13 +2,17 @@
 
 import { Timer } from '@performant-software/shared-components';
 import React, { useCallback, useRef, useState } from 'react';
-import { Icon, Input, InputProps } from 'semantic-ui-react';
+import { Icon, Input, type InputProps } from 'semantic-ui-react';
 import _ from 'underscore';
 import { type SearchBoxProps } from '../types/InstantSearch';
 
-type Props = typeof InputProps & SearchBoxProps;
+type Props = InputProps & SearchBoxProps;
 
-const SearchBox = ({ useSearchBox, ...props }: typeof Props) => {
+/**
+ * This component is used with the `useSearchBox` function from Instant Search Hooks and renders an input element that
+ * when changed will execute a new query.
+ */
+const SearchBox = ({ useSearchBox, ...props }: Props) => {
   const {
     query,
     refine,

package/src/components/SearchPagination.js

@@ -5,9 +5,17 @@ import { Pagination } from 'semantic-ui-react';
 import { type PaginationProps } from '../types/InstantSearch';
 
 type Props = PaginationProps & {
+  /**
+   * If `true`, we'll scroll to the top of the page after applying the new page value.
+   */
   scrollToTop?: boolean
 };
 
+/**
+ * This component is used with the `usePagination` hook from Instant Search Hooks and renders a list of page numbers
+ * that can be selected by the user. If the `scrollToTop` prop is set to `true`, the window will scroll to the top
+ * after applying a new value.
+ */
 const SearchPagination = ({ usePagination, ...props }: Props) => {
   const { currentRefinement, nbPages: pages, refine } = usePagination(props);
   const onPageChange = useCallback((e, { activePage }) => refine(activePage - 1), [refine]);