docs: Add docs to /Schema files

editor.planx.uk/src/@planx/components/shared/Schema/Fields.tsx

@@ -38,6 +38,9 @@ type Props<T extends Field> = {
   activeIndex: number;
 } & T;
 
+/**
+ * Helper function to get shared props derived from `Field` and `props.formik`
+ */
 const getFieldProps = <T extends Field>(props: Props<T>) => ({
   id: `input-${props.type}-${props.data.fn}`,
   errorMessage: get(props.formik.errors, ["userData", props.activeIndex, props.data.fn]),

editor.planx.uk/src/@planx/components/shared/Schema/SchemaFields.tsx

@@ -36,11 +36,20 @@ const InputField: React.FC<InputFieldProps> = (props) => {
 };
 
 interface SchemaFieldsProps { 
+  /** 
+   * Optional index of currently active schema instance. 
+   * Only required if multiple user responses are allowed, e.g. in the List component. 
+   * Defaults to 0 as `UserData` always holds an array of responses
+  */
   activeIndex?: number;
+  /** Formik instance generated from config provided by useSchema hook */
   formik: FormikProps<UserData>;
   schema: Schema;
 }
 
+/**
+ * Display a set of fields for the provided schema
+ */
 export const SchemaFields: React.FC<SchemaFieldsProps> = ({ schema, formik, activeIndex = 0 }) => (
   schema.fields.map((field, i) => (
     <InputRow key={i}>

editor.planx.uk/src/@planx/components/shared/Schema/hook.tsx

@@ -2,15 +2,31 @@ import { FormikConfig } from "formik";
 
 import { generateInitialValues, generateValidationSchema, Schema, UserData, UserResponse } from "./model";
 
-interface Props {
+type UseSchema = (props: {
   schema: Schema;
   previousValues?: UserResponse[];
+}) => {
+  /**
+   * Extensible Formik config which allows custom form state and submission logic
+   * @example const formik = useFormik<UserData & MyCustomState>(...)
+   * @example const formik = useFormik<UserData>(...formikConfig, onSubmit: () => {...})
+  */
+  formikConfig: Omit<FormikConfig<UserData>, "onSubmit">,
+  /** 
+   * A blank set of initial values matching the schema
+   * Can be if multiple responses are allowed (e.g. in the List component)
+  */
+  initialValues: UserResponse,
 }
 
-export const useSchema = ({
+/**
+ * Hook which allows you to embed a group of fields, described by a schema, within another component
+ * Form state and custom logic is stored and managed within the parent component
+ */
+export const useSchema: UseSchema = ({
   schema,
   previousValues,
-}: Props) => {
+}) => {
   const validationSchema = generateValidationSchema(schema);
   const initialValues = generateInitialValues(schema);
 
@@ -20,7 +36,7 @@ export const useSchema = ({
     return schema.min ? [initialValues] : [];
   };
 
-  const formikConfig: Omit<FormikConfig<UserData>, "onSubmit"> = {
+  const formikConfig = {
     initialValues: {
       userData: getInitialValues(),
     },
@@ -29,5 +45,5 @@ export const useSchema = ({
     validationSchema,
   }
 
-  return { formikConfig, initialValues, };
+  return { formikConfig, initialValues };
 }

editor.planx.uk/src/@planx/components/shared/Schema/model.ts

@@ -109,6 +109,9 @@ export interface Schema {
 
 export type UserResponse = Record<Field["data"]["fn"], string | any[]>; // string | string[] | Feature[]
 
+/**
+ * Output data from a form using the useSchema hook
+ */
 export type UserData = { userData: UserResponse[] };
 
 /**