Document and improve editables

components/contexts/editing.tsx

@@ -1,4 +0,0 @@
-import { createStateContext } from "../../utils/stateContext";
-
-
-export const EditingContext = createStateContext<boolean>()

components/contexts/login.tsx

@@ -5,8 +5,8 @@ import { createStateContext } from "../../utils/stateContext";
 /**
  * Context containing data about the user's current login status:
  * - `null` if the user is not logged in
- * - an instance of {@link LoginData} if the user is logged in
+ * - an instance of {@link FestaLoginData} if the user is logged in
  * 
- * Please note that the data containing in this context is not validated, and will need to be validated by the server on every request.
+ * Please note that the data containing in this context is not validated, and will be validated by the server on every request.
  */
 export const LoginContext = createStateContext<FestaLoginData | null>()

components/editable/EditableDateRange.tsx

@@ -1,6 +1,6 @@
 import { faChevronRight, faClock } from "@fortawesome/free-solid-svg-icons"
 import { HTMLProps } from "react"
-import { EditingContext } from "../contexts/editing"
+import { EditingContext } from "./EditingContext"
 import { useDefinedContext } from "../../utils/definedContext"
 import { FestaIcon } from "../extensions/FestaIcon"
 import { FormDateRange } from "../form/FormDateRange"

components/editable/EditableMarkdown.tsx

@@ -1,9 +1,11 @@
 import { HTMLProps } from "react";
-import { EditingContext } from "../contexts/editing";
+import { EditingContext } from "./EditingContext";
 import { useDefinedContext } from "../../utils/definedContext";
 import { FestaMarkdown } from "../extensions/FestaMarkdown";
 
-
+/**
+ * Controlled input component which displays a `textarea` in editing mode, and renders the input in Markdown using {@link FestaMarkdown} in preview mode.
+ */
 export function EditableMarkdown({value, ...props}: HTMLProps<HTMLTextAreaElement>) {
     const [editing,] = useDefinedContext(EditingContext)
 

components/editable/EditablePostcard.tsx

@@ -1,9 +1,14 @@
 import { HTMLProps } from "react";
-import { EditingContext } from "../contexts/editing";
+import { EditingContext } from "./EditingContext";
 import { useDefinedContext } from "../../utils/definedContext";
 import { Postcard } from "../postcard/Postcard";
 
 
+/**
+ * Controlled input component which displays an `input[type="file"]` in editing mode, and is invisible in preview mode.
+ * 
+ * As a side effect, it changes the {@link Postcard} to the input file when it's rendered.
+ */
 export function EditablePostcard({value, ...props}: HTMLProps<HTMLInputElement> & {value: string | undefined}) {
     const [editing,] = useDefinedContext(EditingContext)
 

components/editable/EditableText.tsx

@@ -1,14 +1,17 @@
 import { HTMLProps } from "react";
-import { EditingContext } from "../contexts/editing";
+import { EditingContext } from "./EditingContext";
 import { useDefinedContext } from "../../utils/definedContext";
 
 
-export function EditableText({value, ...props}: HTMLProps<HTMLInputElement>) {
+/**
+ * Controlled input component which displays an `input[type="text"]` in editing mode, and a `span` displaying the input in preview mode.
+ */
+export function EditableText(props: HTMLProps<HTMLInputElement> & {value: string}) {
     const [editing,] = useDefinedContext(EditingContext)
 
     return editing ? (
-        <input type="text" value={value} {...props}/>
+        <input type="text" {...props}/>
     ) : (
-        <span>{value}</span>
+        <span>{props.value}</span>
     )
 }

components/editable/EditingContext.ts

@@ -0,0 +1,9 @@
+import { createStateContext } from "../../utils/stateContext";
+
+
+/**
+ * {@link createStateContext State context} representing the editing state of a form.
+ * 
+ * If `true`, the components should be editable, while if `false`, the components should preview their contents.
+ */
+export const EditingContext = createStateContext<boolean>()

components/editable/README.md

@@ -0,0 +1,7 @@
+# Editables
+
+This folder contains controlled input components with two modes: a "editing" mode, which displays a box where the user can input data, and a "preview" mode, which renders the value of the data input by the user.
+
+For example, [`EditableMarkdown`](EditableMarkdown.tsx) displays a `textarea` in editing mode, and renders the Markdown into a `div` in preview mode.
+
+The mode of the elements is determined by the current value of the [`EditingContext`](EditingContext.ts) they are in.

components/tools/ToolToggleEditing.tsx

@@ -1,6 +1,6 @@
 import { faBinoculars, faPencil } from "@fortawesome/free-solid-svg-icons"
 import { useTranslation } from "next-i18next"
-import { EditingContext } from "../contexts/editing"
+import { EditingContext } from "../editable/EditingContext"
 import { useDefinedContext } from "../../utils/definedContext"
 import { FestaIcon } from "../extensions/FestaIcon"
 

pages/events/[slug].tsx

@@ -8,7 +8,7 @@ import { ToolBar } from "../../components/tools/ToolBar";
 import { EditableMarkdown } from "../../components/editable/EditableMarkdown";
 import { EditableText } from "../../components/editable/EditableText";
 import { ToolToggleEditing } from "../../components/tools/ToolToggleEditing";
-import { EditingContext } from "../../components/contexts/editing";
+import { EditingContext } from "../../components/editable/EditingContext";
 import { database } from "../../utils/prismaClient";
 import { EditablePostcard } from "../../components/editable/EditablePostcard";
 import { ViewEvent } from "../../components/view/ViewEvent";