Documentation, add Collections new form #747

browser/data-browser/src/components/forms/NewForm/CustomCreateActions/BasicInstanceHandlers.ts

@@ -1,6 +1,10 @@
 import { dataBrowser, core, classes, server } from '@tomic/react';
 import { registerBasicInstanceHandler } from '../useNewResourceUI';
 
+/**
+ * These handlers do not show any UI / inputs when creating new instances.
+ * This is where they can have hardcoded default values or custom logic.
+ */
 export const registerBasicInstanceHandlers = () => {
   registerBasicInstanceHandler(
     dataBrowser.classes.folder,
@@ -29,20 +33,6 @@ export const registerBasicInstanceHandlers = () => {
     },
   );
 
-  registerBasicInstanceHandler(
-    dataBrowser.classes.folder,
-    async (parent, createAndNavigate) => {
-      await createAndNavigate(
-        dataBrowser.classes.folder,
-        {
-          [core.properties.name]: 'Untitled Folder',
-          [dataBrowser.properties.displayStyle]: classes.displayStyles.list,
-        },
-        parent,
-      );
-    },
-  );
-
   registerBasicInstanceHandler(
     dataBrowser.classes.document,
     async (parent, createAndNavigate) => {

browser/data-browser/src/components/forms/NewForm/CustomCreateActions/CustomForms/NewCollectionDialog.tsx

@@ -0,0 +1,101 @@
+import { JSONValue, collections, core } from '@tomic/react';
+import { useState, useCallback, FormEvent, useEffect, FC } from 'react';
+import { Button } from '../../../../Button';
+import {
+  useDialog,
+  Dialog,
+  DialogTitle,
+  DialogContent,
+  DialogActions,
+} from '../../../../Dialog';
+import Field from '../../../Field';
+import { InputWrapper, InputStyled } from '../../../InputStyles';
+import { CustomResourceDialogProps } from '../../useNewResourceUI';
+import { useCreateAndNavigate } from '../../../../../hooks/useCreateAndNavigate';
+import { ResourceSelector } from '../../../ResourceSelector';
+
+export const NewCollectionDialog: FC<CustomResourceDialogProps> = ({
+  parent,
+  onClose,
+}) => {
+  const [name, setName] = useState('New Collection');
+  const [valueFilter, setValue] = useState<string | undefined>();
+  const [propertyFilter, setProperty] = useState<string | undefined>();
+
+  const [dialogProps, show, hide] = useDialog({ onCancel: onClose });
+
+  const createResourceAndNavigate = useCreateAndNavigate();
+
+  const onDone = useCallback(
+    (e: FormEvent) => {
+      e.preventDefault();
+
+      createResourceAndNavigate(
+        collections.classes.collection,
+        {
+          [core.properties.name]: name,
+          [collections.properties.value]: valueFilter,
+          [collections.properties.property]: propertyFilter,
+          [collections.properties.pageSize]: 30,
+          [collections.properties.currentPage]: 0,
+        },
+        parent,
+      );
+
+      onClose();
+    },
+    [valueFilter, onClose, propertyFilter],
+  );
+
+  useEffect(() => {
+    show();
+  }, []);
+
+  return (
+    <Dialog {...dialogProps}>
+      <DialogTitle>
+        <h1>New Collection</h1>
+      </DialogTitle>
+      <DialogContent>
+        <form onSubmit={onDone}>
+          <Field required label='name'>
+            <InputWrapper>
+              <InputStyled
+                placeholder='Name your Collection'
+                value={name}
+                autoFocus={true}
+                onChange={e => setName(e.target.value)}
+              />
+            </InputWrapper>
+          </Field>
+          <Field label='property'>
+            <div>
+              <ResourceSelector
+                isA={core.classes.property}
+                setSubject={setProperty}
+                value={propertyFilter}
+              />
+            </div>
+          </Field>
+          <Field label='value'>
+            <InputWrapper>
+              <InputStyled
+                placeholder='Set a value filter (optional)'
+                value={valueFilter}
+                onChange={e => setValue(e.target.value)}
+              />
+            </InputWrapper>
+          </Field>
+        </form>
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={() => hide(false)} subtle>
+          Cancel
+        </Button>
+        <Button onClick={onDone} disabled={!propertyFilter && !valueFilter}>
+          Ok
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+};

browser/data-browser/src/components/forms/NewForm/CustomCreateActions/CustomForms/index.ts

@@ -1,11 +1,16 @@
-import { dataBrowser, core } from '@tomic/react';
+import { dataBrowser, core, collections } from '@tomic/react';
 import { registerNewResourceDialog } from '../../useNewResourceUI';
 import { NewBookmarkDialog } from './NewBookmarkDialog';
 import { NewOntologyDialog } from './NewOntologyDialog';
 import { NewTableDialog } from './NewTableDialog';
+import { NewCollectionDialog } from './NewCollectionDialog';
 
 export const registerCustomForms = () => {
   registerNewResourceDialog(dataBrowser.classes.bookmark, NewBookmarkDialog);
   registerNewResourceDialog(core.classes.ontology, NewOntologyDialog);
   registerNewResourceDialog(dataBrowser.classes.table, NewTableDialog);
+  registerNewResourceDialog(
+    collections.classes.collection,
+    NewCollectionDialog,
+  );
 };

browser/data-browser/src/components/forms/NewForm/NewFormTitle.tsx

@@ -2,7 +2,6 @@ import { properties, useResource, useString, useTitle } from '@tomic/react';
 import { useState } from 'react';
 import { FaInfo } from 'react-icons/fa';
 import { AtomicLink } from '../../AtomicLink';
-import { Button } from '../../Button';
 import Markdown from '../../datatypes/Markdown';
 import { Column, Row } from '../../Row';
 import styled from 'styled-components';

browser/data-browser/src/components/forms/NewForm/useNewResourceUI.tsx

@@ -21,6 +21,7 @@ export interface CustomResourceDialogProps {
   onClose: () => void;
 }
 
+/**  When creating a new resource, the matched handler is called */
 export type BasicInstanceHandler = (
   parent: string,
   createAndNavigate: CreateAndNavigate,
@@ -37,19 +38,28 @@ interface NewResourceUIContext {
 const dialogs = new Map<string, FC<CustomResourceDialogProps>>();
 const basicNewInstanceHandlers = new Map<string, BasicInstanceHandler>();
 
+/**
+ * Returns a function that when called, renders UI to create a new Resource of the given class.
+ *
+ * Use {@link registerNewResourceDialog} to register a custom dialog for a given class.
+ */
 export function useNewResourceUI() {
   const { showNewResourceUI } = useContext(NewResourceUIContext);
 
   return showNewResourceUI;
 }
 
+/** Call this when adding a new custom New Resource Form / Dialog. */
 export const registerNewResourceDialog = (
   classSubject: string,
   component: FC<CustomResourceDialogProps>,
 ) => {
   dialogs.set(classSubject, component);
 };
 
+/** Call this when adding a new custom action for a New Resource that does _not_ require inputs.
+ * For example, creating a new Folder does not require any inputs, so it can be handled without any UI.
+ */
 export const registerBasicInstanceHandler = (
   classSubject: string,
   handler: BasicInstanceHandler,
@@ -61,6 +71,7 @@ const NewResourceUIContext = createContext<NewResourceUIContext>({
   showNewResourceUI: () => undefined,
 });
 
+/** Renders the Dialog used when creating new resources. */
 export function NewResourceUIProvider({ children }: PropsWithChildren) {
   const store = useStore();
   const settings = useSettings();

browser/data-browser/src/hooks/useCreateAndNavigate.ts

@@ -16,7 +16,7 @@ export type CreateAndNavigate = (
  * Hook that builds a function that will create a new resource with the given
  * properties and then navigate to it.
  *
- * @returns A createAndNavigate function.
+ * @returns A {@link CreateAndNavigate} function.
  */
 export function useCreateAndNavigate(): CreateAndNavigate {
   const store = useStore();