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

package/types/components/FacetList.js.flow

@@ -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/types/components/FacetSlider.js.flow

@@ -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/types/components/FacetToggle.js.flow

@@ -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/types/components/SearchBox.js.flow

@@ -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/types/components/SearchPagination.js.flow

@@ -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]);

package/types/components/SearchResults.js.flow

@@ -5,17 +5,56 @@ import ItemCollection from './ItemCollection';
 import { type HitsProps } from '../types/InstantSearch';
 
 type Props = HitsProps & {
+  /**
+   * Renders the component as the passed `as` prop.
+   */
   as?: Element<any>,
+
+  /**
+   * Additional props to pass to the container component.
+   */
   asProps?: any,
+
+  /**
+   * If `true` each item will be rendered as a Link.
+   */
   link?: boolean,
+
+  /**
+   * Renders the description for the passed item.
+   */
   renderDescription?: (item: any) => Node,
+
+  /**
+   * Component to render if the list contains no records.
+   */
   renderEmptyList?: () => Node,
+
+  /**
+   * Renders the extra content for the passed item.
+   */
   renderExtra?: (item: any) => Node,
+
+  /**
+   * Renders the header for the passed item.
+   */
   renderHeader?: (item: any) => Node,
+
+  /**
+   * Renders the image for the passed item.
+   */
   renderImage?: (item: any) => Node,
+
+  /**
+   * Renders the meta for the passed item.
+   */
   renderMeta?: (item: any) => Node
 };
 
+/**
+ * This component is used with the `useHits` hook from Instant Search Hooks and renders a pass-through to the
+ * `ItemCollection` component.
+ */
 const SearchResults = ({ useHits, ...props }: Props) => {
   const { hits } = useHits(props);
 

package/types/components/SearchResultsPerPage.js.flow

@@ -7,9 +7,16 @@ import i18n from '../i18n/i18n';
 import { type HitsPerPageProps } from '../types/InstantSearch';
 
 type Props = HitsPerPageProps & {
+  /**
+   * An array of numeric values to present to the user as the number of records to display per page.
+   */
   options: Array<number>
 };
 
+/**
+ * This component is used with the `useHitsPerPage` hook from Instant Search Hooks and renders a dropdown with
+ * options for the number of records to display per page.
+ */
 const SearchResultsPerPage = ({ useHitsPerPage, options }: Props) => {
   const { items, refine } = useHitsPerPage({
     items: _.map(options, (option, index) => ({

package/types/components/SearchStats.js.flow

@@ -7,6 +7,10 @@ import type { StatsProps } from '../types/InstantSearch';
 const MsToS = 1000.0;
 const DECIMAL_PLACES = 2;
 
+/**
+ * This component is used with the `useStats` hook from Instant Search Hooks and renders a label of the number of
+ * records returned and the time it took to execute the request.
+ */
 const SearchStats = ({ useStats, ...props }: StatsProps) => {
   const { nbHits: count, processingTimeMS } = useStats(props);
   const seconds = (processingTimeMS / MsToS).toFixed(DECIMAL_PLACES);

package/types/components/StyleSelector.js.flow

@@ -6,10 +6,21 @@ import { Dropdown } from 'semantic-ui-react';
 import _ from 'underscore';
 
 type Props = {
+  /**
+   * Callback fired when the style selector is changed.
+   */
   onChange: (name: string, xml: string) => void,
-  value: ?string
+
+  /**
+   * Default style value.
+   */
+  value?: string
 };
 
+/**
+ * This component can be used, along with the `useCitationStyles` hook, to display a list of bibliographic styles
+ * supported by Zotero.
+ */
 const StyleSelector = (props: Props) => {
   const { onStyleChange, style, styles } = useCitationStyles(props.value);
 

package/types/index.js.flow

@@ -10,7 +10,9 @@ export { default as AccordionSelector } from './components/AccordionSelector';
 export { default as ArrowButtons } from './components/ArrowButtons';
 export { default as AssociatedDropdown } from './components/AssociatedDropdown';
 export { default as AudioPlayer } from './components/AudioPlayer';
+export { default as BibliographyForm } from './components/BibliographyForm';
 export { default as BibliographyList } from './components/BibliographyList';
+export { default as BibliographySearchInput } from './components/BibliographySearchInput';
 export { default as BooleanIcon } from './components/BooleanIcon';
 export { default as CancelButton } from './components/CancelButton';
 export { default as ColorButton } from './components/ColorButton';
@@ -85,6 +87,7 @@ export { default as Section } from './components/Section';
 export { default as Selectize } from './components/Selectize';
 export { default as SelectizeHeader } from './components/SelectizeHeader';
 export { default as SelectizeImageHeader } from './components/SelectizeImageHeader';
+export { default as StyleSelector } from './components/StyleSelector';
 export { default as TabbedModal } from './components/TabbedModal';
 export { default as TabsMenu } from './components/TabsMenu';
 export { default as TagsList } from './components/TagsList';

package/types/types/InstantSearch.js.flow

@@ -1,14 +1,23 @@
 // @flow
 
 export type ClearRefinementsProps = {
+  /**
+   * Instant-Search hook to clear current refinements values.
+   */
   useClearRefinements: (props: any) => ({ canRefine: boolean, refine: () => void })
 };
 
 export type CurrentRefinementsProps = {
+  /**
+   * Instant-Search hook to provide current refinements values.
+   */
   useCurrentRefinements: (props: any) => ({ items: Array<any> })
 };
 
 export type HitsPerPageProps = {
+  /**
+   * Instant-Search hook to provide number of hits per page values.
+   */
   useHitsPerPage: (props: any) => ({
     items: Array<{ value: number, label: string, default: boolean}>,
     refine: (value: number) => void
@@ -16,12 +25,18 @@ export type HitsPerPageProps = {
 };
 
 export type HitsProps = {
+  /**
+   * Instant-Search hook to provide search hits values.
+   */
   useHits: (props: any) => ({
     hits: Array<any>
   })
 };
 
 export type PaginationProps = {
+  /**
+   * Instant-Search hook to provide pagination values.
+   */
   usePagination: (props: any) => ({
     currentRefinement: number,
     nbPages: number,
@@ -30,6 +45,9 @@ export type PaginationProps = {
 };
 
 export type RangeSliderProps = {
+  /**
+   * Instant-Search hook to provide range values.
+   */
   useRangeSlider: (props: any) => ({
     start: Array<number>,
     range: {
@@ -41,6 +59,9 @@ export type RangeSliderProps = {
 };
 
 export type RefinementListProps = {
+  /**
+   * Instant-Search hook to provide refinement list values.
+   */
   useRefinementList: (props: any) => ({
     items: Array<any>,
     refine: (value: any) => void,
@@ -51,6 +72,9 @@ export type RefinementListProps = {
 };
 
 export type SearchBoxProps = {
+  /**
+   * Instant-Search hook to provide search box values.
+   */
   useSearchBox: (props: any) => ({
     query: string,
     refine: (value: string) => void,
@@ -60,6 +84,9 @@ export type SearchBoxProps = {
 };
 
 export type StatsProps = {
+  /**
+   * Instant-Search hook to provide search statistic values.
+   */
   useStats: (props: any) => ({
     nbHits: number,
     processingTimeMS: number
@@ -67,6 +94,9 @@ export type StatsProps = {
 };
 
 export type ToggleRefinementProps = {
+  /**
+   * Instant-Search hook to provide toggle refinement values.
+   */
   useToggleRefinement: (props: any) => ({
     value: {
       isRefined: boolean,