📔 Document a lot of stuff

nest_frontend/components/interactive/BoxConditionDatetime.js

@@ -4,7 +4,7 @@ import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
 import { faClock } from "@fortawesome/free-solid-svg-icons"
 import useRepositoryEditor from "../../hooks/useRepositoryEditor"
 import ContextLanguage from "../../contexts/ContextLanguage"
-import FormInlineBADatetime from "./FormInlineBADatetime"
+import FormInlineTimeRay from "./FormInlineTimeRay"
 import { ConditionTime } from "../../objects/Condition"
 
 
@@ -38,7 +38,7 @@ export default function BoxConditionDatetime({ ...props }) {
             }
             {...props}
         >
-            <FormInlineBADatetime
+            <FormInlineTimeRay
                 submit={submit}
             />
         </BoxFull>

nest_frontend/components/interactive/BoxFilterContains.js

@@ -2,18 +2,26 @@ import React from "react"
 import BoxFull from "../base/BoxFull"
 import useRepositoryViewer from "../../hooks/useRepositoryViewer"
 import useStrings from "../../hooks/useStrings"
-import { FilterContains } from "../../utils/Filter"
+import { FilterContains } from "../../objects/Filter"
 import FormInlineText from "./FormInlineText"
 import { faFont } from "@fortawesome/free-solid-svg-icons"
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
 
 
+/**
+ * A {@link BoxFull} that allows the user to select a word to search for, and then to add it as a
+ * {@link FilterContains} of a RepositoryViewer.
+ *
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxFilterContains({ ...props }) {
     const strings = useStrings()
     const { appendFilter } = useRepositoryViewer()
 
     const submit = value => {
-        appendFilter(new FilterContains(false, value))
+        appendFilter(new FilterContains(value))
     }
 
     // TODO: add this string

nest_frontend/components/interactive/BoxFilterDatetime.js

@@ -1,19 +1,27 @@
 import React from "react"
 import BoxFull from "../base/BoxFull"
-import { faClock, faHashtag } from "@fortawesome/free-solid-svg-icons"
+import { faClock } from "@fortawesome/free-solid-svg-icons"
 import useRepositoryViewer from "../../hooks/useRepositoryViewer"
 import useStrings from "../../hooks/useStrings"
-import { FilterInsideTimeRay } from "../../utils/Filter"
+import { FilterInsideTimeRay } from "../../objects/Filter"
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
-import FormInlineBADatetime from "./FormInlineBADatetime"
+import FormInlineTimeRay from "./FormInlineTimeRay"
 
 
+/**
+ * A {@link BoxFull} that allows the user to select a {@link TimeRay}, and then to add it as a
+ * {@link FilterInsideTimeRay} of a RepositoryViewer.
+ *
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxFilterDatetime({ ...props }) {
     const strings = useStrings()
     const { appendFilter } = useRepositoryViewer()
 
-    const submit = ({ date, isBefore }) => {
-        appendFilter(new FilterInsideTimeRay(isBefore, date))
+    const submit = ({ timeRay }) => {
+        appendFilter(new FilterInsideTimeRay(timeRay))
     }
 
     return (
@@ -29,7 +37,7 @@ export default function BoxFilterDatetime({ ...props }) {
             }
             {...props}
         >
-            <FormInlineBADatetime submit={submit}/>
+            <FormInlineTimeRay submit={submit}/>
         </BoxFull>
     )
 }

nest_frontend/components/interactive/BoxFilterHasPlace.js

@@ -5,17 +5,24 @@ import useRepositoryViewer from "../../hooks/useRepositoryViewer"
 import useStrings from "../../hooks/useStrings"
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
 import { faLocationArrow, faPlus } from "@fortawesome/free-solid-svg-icons"
-import { FilterWithPlace } from "../../utils/Filter"
+import { FilterWithPlace } from "../../objects/Filter"
 import ButtonIconOnly from "../base/ButtonIconOnly"
 
 
+/**
+ * A {@link BoxFull} that allows the user to add a {@link FilterWithPlace} to a RepositoryViewer.
+ *
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxFilterHasPlace({ ...props }) {
     const strings = useStrings()
 
     const { appendFilter } = useRepositoryViewer()
 
     const submit = () => {
-        appendFilter(new FilterWithPlace(false))
+        appendFilter(new FilterWithPlace())
     }
 
     // TODO: translate this

nest_frontend/components/interactive/BoxFilterHashtag.js

@@ -3,17 +3,25 @@ import BoxFull from "../base/BoxFull"
 import { faClock } from "@fortawesome/free-solid-svg-icons"
 import useRepositoryViewer from "../../hooks/useRepositoryViewer"
 import useStrings from "../../hooks/useStrings"
-import { FilterHashtag } from "../../utils/Filter"
+import { FilterHashtag } from "../../objects/Filter"
 import FormInlineHashtag from "./FormInlineHashtag"
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
 
 
+/**
+ * A {@link BoxFull} that allows the user to select a Twitter hashtag to search for, and then to add it as a
+ * {@link FilterContains} of a RepositoryViewer.
+ *
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxFilterHashtag({ ...props }) {
     const strings = useStrings()
     const { appendFilter } = useRepositoryViewer()
 
     const submit = value => {
-        appendFilter(new FilterHashtag(false, value))
+        appendFilter(new FilterHashtag(value))
     }
 
     return (

nest_frontend/components/interactive/BoxFilterLocation.js

@@ -1,14 +1,22 @@
 import React from "react"
 import BoxFull from "../base/BoxFull"
-import FormInline from "../base/FormInline"
 import useRepositoryViewer from "../../hooks/useRepositoryViewer"
 import useStrings from "../../hooks/useStrings"
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
 import { faMapPin } from "@fortawesome/free-solid-svg-icons"
 import FormInlineLocation from "./FormInlineLocation"
-import { FilterInsideMapArea } from "../../utils/Filter"
+import { FilterInsideMapArea } from "../../objects/Filter"
 
 
+/**
+ * A {@link BoxFull} that allows the user to add a {@link FilterInsideMapArea} to a RepositoryViewer.
+ *
+ * It connects to the `mapViewHook` of the RepositoryViewer.
+ *
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxFilterLocation({ ...props }) {
     const strings = useStrings()
 

nest_frontend/components/interactive/BoxFilterUser.js

@@ -3,20 +3,26 @@ import BoxFull from "../base/BoxFull"
 import { faAt } from "@fortawesome/free-solid-svg-icons"
 import useRepositoryViewer from "../../hooks/useRepositoryViewer"
 import useStrings from "../../hooks/useStrings"
-import { FilterPoster } from "../../utils/Filter"
+import { FilterPoster } from "../../objects/Filter"
 import FormInlineUser from "./FormInlineUser"
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
 
 
+/**
+ * A {@link BoxFull} that allows the user to select a Twitter user to search for, and then to add it as a
+ * {@link FilterPoster} of a RepositoryViewer.
+ *
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxFilterUser({ ...props }) {
-    // TODO: Translate this
-    // TODO: and also use a better string maybe
     const strings = useStrings()
 
     const { appendFilter } = useRepositoryViewer()
 
     const submit = value => {
-        appendFilter(new FilterPoster(false, value))
+        appendFilter(new FilterPoster(value))
     }
 
     return (

nest_frontend/components/interactive/BoxFilters.js

@@ -19,6 +19,7 @@ export default function BoxFilters({ ...props }) {
     const badges = filters.map((filter, pos) => <BadgeFilter key={pos} filter={filter}/>)
 
     // TODO: localize this
+
     return (
         <BoxFull header={"Filters"} {...props}>
             {badges}

nest_frontend/components/interactive/BoxLoggedIn.js

@@ -13,7 +13,7 @@ import ContextLanguage from "../../contexts/ContextLanguage"
 /**
  * A {@link BoxFull} displaying the user's current login status, and allowing them to logout.
  *
- * @param props
+ * @param props - Additional props to pass to the box.
  * @returns {JSX.Element}
  * @constructor
  */

nest_frontend/components/interactive/BoxRepositoryCreate.module.css

@@ -1,3 +0,0 @@
-.BoxRepositoryCreate {
-
-}

nest_frontend/components/interactive/BoxRepositoryTweets.js

@@ -1,14 +1,22 @@
-import React, { useContext } from "react"
+import React from "react"
 import BoxFullScrollable from "../base/BoxFullScrollable"
 import SummaryTweet from "./SummaryTweet"
-import ContextLanguage from "../../contexts/ContextLanguage"
 import Empty from "./Empty"
-import ContextRepositoryViewer from "../../contexts/ContextRepositoryViewer"
+import useRepositoryViewer from "../../hooks/useRepositoryViewer"
+import useStrings from "../../hooks/useStrings"
 
 
+/**
+ * A {@link BoxFullScrollable} rendering all the tweets currently displayed in a RepositoryViewer as
+ * {@link SummaryTweet}s.
+ *
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxRepositoryTweets({ ...props }) {
-    const { strings } = useContext(ContextLanguage)
-    const { tweets } = useContext(ContextRepositoryViewer)
+    const strings = useStrings()
+    const { tweets } = useRepositoryViewer()
 
     let content
     if(tweets.length === 0) {

nest_frontend/components/interactive/BoxUserCreate.js

@@ -9,6 +9,15 @@ import FormAlert from "../base/formparts/FormAlert"
 import ContextLanguage from "../../contexts/ContextLanguage"
 
 
+/**
+ * A {@link BoxFull} allowing an administrator user to create a new user.
+ *
+ * @param createUser - Async function to call to create an user.
+ * @param running - Whether another request is currently running.
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxUserCreate({ createUser, running, ...props }) {
     const [username, setUsername] = useState("")
     const [email, setEmail] = useState("")

nest_frontend/components/interactive/BoxUserList.js

@@ -5,6 +5,16 @@ import SummaryUser from "./SummaryUser"
 import ContextLanguage from "../../contexts/ContextLanguage"
 
 
+/**
+ * A {@link BoxFullScrollable} rendering an array of users as {@link SummaryUser}s.
+ *
+ * @param users - Array of users to render.
+ * @param destroyUser - Async function to destroy an user, to be passed to {@link SummaryUser}.
+ * @param running - Whether another request is currently running.
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxUserList({ users, destroyUser, running, ...props }) {
     const { strings } = useContext(ContextLanguage)
 

nest_frontend/components/interactive/BoxVisualizationMap.js

@@ -2,10 +2,17 @@ import React, { useContext, useMemo } from "react"
 import BoxMap from "../base/BoxMap"
 import ContextLanguage from "../../contexts/ContextLanguage"
 import { Marker, Popup } from "react-leaflet"
-import { Location } from "../../utils/location"
+import { Location } from "../../objects/location"
 import ContextRepositoryViewer from "../../contexts/ContextRepositoryViewer"
 
 
+/**
+ * A {@link BoxMap} displaying the displayed tweets of a RepositoryViewer as {@link Marker}s.
+ *
+ * @param props - Additional props to pass to the box.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function BoxVisualizationMap({ ...props }) {
     const { strings } = useContext(ContextLanguage)
     const { tweets, mapViewHook } = useContext(ContextRepositoryViewer)

nest_frontend/components/interactive/BoxVisualizationWordcloud.js

@@ -1,10 +1,10 @@
-import React, { useContext } from "react"
+import React, { useCallback, useContext } from "react"
 import BoxWordcloud from "../base/BoxWordcloud"
 import ContextLanguage from "../../contexts/ContextLanguage"
 import BoxFull from "../base/BoxFull"
 import Empty from "./Empty"
 import ContextRepositoryViewer from "../../contexts/ContextRepositoryViewer"
-import { FilterContains } from "../../utils/Filter"
+import { FilterContains } from "../../objects/Filter"
 
 
 export default function BoxVisualizationWordcloud({ ...props }) {
@@ -19,9 +19,12 @@ export default function BoxVisualizationWordcloud({ ...props }) {
         )
     }
 
-    const onWordClick = word => {
-        appendFilter(new FilterContains(false, word.text))
-    }
+    const onWordClick = useCallback(
+        word => {
+            appendFilter(new FilterContains(word.text))
+        },
+        [appendFilter]
+    )
 
     return (
         <BoxWordcloud

nest_frontend/components/interactive/ButtonPicker.js

@@ -2,6 +2,16 @@ import React from "react"
 import ButtonIconOnly from "../base/ButtonIconOnly"
 
 
+/**
+ * A {@link ButtonIconOnly} to be used to switch between RepositoryViewer tabs.
+ *
+ * @param setTab - Function to change tab.
+ * @param currentTab - Name of the current tab, as a string.
+ * @param name - Name of the tab this button should switch to, as a string.
+ * @param props - Additional props to pass to the button.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function ButtonPicker({ setTab, currentTab, name, ...props }) {
     return (
         <ButtonIconOnly

nest_frontend/components/interactive/ButtonToggleBeforeAfter.js

@@ -5,6 +5,16 @@ import Button from "../base/Button"
 import ContextLanguage from "../../contexts/ContextLanguage"
 
 
+/**
+ * A {@link Button} allowing the user to select between **Before** and **After**.
+ *
+ * @param isBefore - The current value of the button.
+ * @param setBefore - Function to set the current value of the button.
+ * @param className - Additional class(es) to append to the button.
+ * @param props - Additional props to pass to the button.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function ButtonToggleBeforeAfter({ isBefore, setBefore, className, ...props }) {
     const { strings } = useContext(ContextLanguage)
 

nest_frontend/components/interactive/Empty.js

@@ -4,7 +4,15 @@ import classNames from "classnames"
 import ContextLanguage from "../../contexts/ContextLanguage"
 
 
-export default function Empty({ children, className, ...props }) {
+/**
+ * A simple inline `<i>` element to be used when there is nothing to be displayed inside a box.
+ *
+ * @param className - Additional class(es) to append to the element.
+ * @param props - Additional props to pass to the element.
+ * @returns {JSX.Element}
+ * @constructor
+ */
+export default function Empty({ className, ...props }) {
     const { strings } = useContext(ContextLanguage)
 
     return (

nest_frontend/components/interactive/FormInlineHashtag.js

@@ -8,6 +8,14 @@ import { faHashtag } from "@fortawesome/free-solid-svg-icons"
 const INVALID_CHARACTERS = /([^a-z0-9_\u00c0-\u00d6\u00d8-\u00f6\u00f8-\u00ff\u0100-\u024f\u0253-\u0254\u0256-\u0257\u0300-\u036f\u1e00-\u1eff\u0400-\u04ff\u0500-\u0527\u2de0-\u2dff\ua640-\ua69f\u0591-\u05bf\u05c1-\u05c2\u05c4-\u05c5\u05d0-\u05ea\u05f0-\u05f4\ufb12-\ufb28\ufb2a-\ufb36\ufb38-\ufb3c\ufb40-\ufb41\ufb43-\ufb44\ufb46-\ufb4f\u0610-\u061a\u0620-\u065f\u066e-\u06d3\u06d5-\u06dc\u06de-\u06e8\u06ea-\u06ef\u06fa-\u06fc\u0750-\u077f\u08a2-\u08ac\u08e4-\u08fe\ufb50-\ufbb1\ufbd3-\ufd3d\ufd50-\ufd8f\ufd92-\ufdc7\ufdf0-\ufdfb\ufe70-\ufe74\ufe76-\ufefc\u200c\u0e01-\u0e3a\u0e40-\u0e4e\u1100-\u11ff\u3130-\u3185\ua960-\ua97f\uac00-\ud7af\ud7b0-\ud7ff\uffa1-\uffdc\u30a1-\u30fa\u30fc-\u30fe\uff66-\uff9f\uff10-\uff19\uff21-\uff3a\uff41-\uff5a\u3041-\u3096\u3099-\u309e\u3400-\u4dbf\u4e00-\u9fff\u20000-\u2a6df\u2a700-\u2b73\u2b740-\u2b81\u2f800-\u2fa1])/g
 
 
+/**
+ * A {@link FormInline} allowing the user to select a Twitter hashtag.
+ *
+ * @param submit - Function <string> called when the submit button is pressed.
+ * @param props - Additional props to pass to the form.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function FormInlineHashtag({ submit, ...props }) {
 
     const validate = value => {

nest_frontend/components/interactive/FormInlineLocation.js

@@ -6,6 +6,21 @@ import ButtonIconOnly from "../base/ButtonIconOnly"
 import Style from "./FormInlineLocation.module.css"
 
 
+/**
+ * @deprecated to be refactored
+ * @param mapViewHook
+ * @param radIcon
+ * @param latIcon
+ * @param lngIcon
+ * @param buttonIcon
+ * @param buttonColor
+ * @param placeholder
+ * @param validate
+ * @param submit
+ * @param props
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function FormInlineLocation(
     {
         mapViewHook,

nest_frontend/components/interactive/FormInlineText.js

@@ -6,6 +6,19 @@ import ButtonIconOnly from "../base/ButtonIconOnly"
 import Style from "./FormInlineText.module.css"
 
 
+/**
+ * A {@link FormInline} allowing the user to enter a string.
+ *
+ * @param textIcon - The icon to display in the text field.
+ * @param buttonIcon - The icon to display on the submit button.
+ * @param buttonColor - The color of the submit button.
+ * @param placeholder - The placeholder of the text field.
+ * @param validate - Function <string -> string> called to set the value of the text field.
+ * @param submit - Function <string> called when the submit button is pressed.
+ * @param props - Additional props to pass to the form.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function FormInlineText(
     {
         textIcon = faFont,

nest_frontend/components/interactive/FormInlineTimeRay.js

@@ -11,7 +11,20 @@ import TimeRay from "../../objects/TimeRay"
 const INVALID_CHARACTERS = /[^0-9TZ:+-]/g
 
 
-export default function FormInlineBADatetime(
+/**
+ * A {@link FormInline} allowing the user to select a {@link TimeRay}.
+ *
+ * @param textIcon - The icon to display in the text field.
+ * @param buttonIcon - The icon to display on the submit button.
+ * @param buttonColor - The color of the submit button.
+ * @param placeholder - The placeholder of the text field.
+ * @param validate - Function <string -> string> called to set the value of the text field.
+ * @param submit - Function <{@link TimeRay}> called when the submit button is pressed.
+ * @param props - Additional props to pass to the form.
+ * @returns {JSX.Element}
+ * @constructor
+ */
+export default function FormInlineTimeRay(
     {
         textIcon = faClock,
         buttonIcon = faPlus,

nest_frontend/components/interactive/FormInlineUser.js

@@ -3,11 +3,17 @@ import FormInlineText from "./FormInlineText"
 import { faAt } from "@fortawesome/free-solid-svg-icons"
 
 
-// Official hashtag regex from https://stackoverflow.com/a/22490853/4334568
-// noinspection RegExpAnonymousGroup,LongLine
 const INVALID_CHARACTERS = /[^a-zA-Z0-9]/g
 
 
+/**
+ * A {@link FormInline} allowing the user to select a Twitter user.
+ *
+ * @param submit - Function <string> called when the submit button is pressed.
+ * @param props - Additional props to pass to the form.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function FormInlineUser({ submit, ...props }) {
 
     const validate = value => {

nest_frontend/components/interactive/PickerFilter.js

@@ -5,6 +5,13 @@ import ButtonPicker from "./ButtonPicker"
 import ContextRepositoryViewer from "../../contexts/ContextRepositoryViewer"
 
 
+/**
+ * Tab selector for the Add Filter box of a RepositoryViewer.
+ *
+ * @param props - Additional props to pass to the div.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function PickerFilter({ ...props }) {
     const { filterTab, setFilterTab, setVisualizationTab } = useContext(ContextRepositoryViewer)
 

nest_frontend/components/interactive/PickerVisualization.js

@@ -4,6 +4,13 @@ import ContextRepositoryViewer from "../../contexts/ContextRepositoryViewer"
 import ButtonPicker from "./ButtonPicker"
 
 
+/**
+ * Tab selector for the Visualization box of a RepositoryViewer.
+ *
+ * @param props - Additional props to pass to the div.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function PickerVisualization({ ...props }) {
     const { visualizationTab, setVisualizationTab } = useContext(ContextRepositoryViewer)
 

nest_frontend/components/interactive/SummaryTweet.js

@@ -6,6 +6,14 @@ import SummaryText from "../base/summary/SummaryText"
 import SummaryRight from "../base/summary/SummaryRight"
 
 
+/**
+ * A {@link SummaryBase} representing a tweet.
+ *
+ * @param tweet - The tweet to represent.
+ * @param props - Additional props to pass to the summary.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function SummaryTweet({ tweet, ...props }) {
     let icon
     if(tweet["location"]) {

nest_frontend/components/interactive/SummaryUser.js

@@ -8,6 +8,16 @@ import SummaryButton from "../base/summary/SummaryButton"
 import SummaryRight from "../base/summary/SummaryRight"
 
 
+/**
+ * A {@link SummaryBase} representing a N.E.S.T. user.
+ *
+ * @param user - The user to represent.
+ * @param destroyUser - Async function <string> to destroy an user from the frontend.
+ * @param running - Whether another request is already running.
+ * @param props - Additional props to pass to the summary.
+ * @returns {JSX.Element}
+ * @constructor
+ */
 export default function SummaryUser({ user, destroyUser, running, ...props }) {
     const { strings } = useContext(ContextLanguage)