diff --git a/src/pages/VisProgPage/visualProgrammingUI/components/EditorWarnings.tsx b/src/pages/VisProgPage/visualProgrammingUI/components/EditorWarnings.tsx index 12438e6..497aac6 100644 --- a/src/pages/VisProgPage/visualProgrammingUI/components/EditorWarnings.tsx +++ b/src/pages/VisProgPage/visualProgrammingUI/components/EditorWarnings.tsx @@ -27,6 +27,9 @@ export type WarningSeverity = | 'WARNING' // Acceptable, but probably undesirable behavior | 'ERROR' // Prevents running program, should be fixed before running program is allowed +/** + * warning scope, include a handleId if the warning is handle specific + */ export type WarningScope = { id: string; handleId?: string; @@ -61,11 +64,26 @@ type ZustandSet = (partial: Partial | ((state: FlowState) => Partial< type ZustandGet = () => FlowState; export type EditorWarningRegistry = { + /** + * stores all editor warnings + */ editorWarningRegistry: WarningRegistry; + /** + * index of warnings by severity + */ severityIndex: SeverityIndex; + /** + * gets all warnings and returns them as a list of warnings + * @returns {EditorWarning[]} + */ getWarnings: () => EditorWarning[]; + /** + * gets all warnings with the current severity + * @param {WarningSeverity} warningSeverity + * @returns {EditorWarning[]} + */ getWarningsBySeverity: (warningSeverity: WarningSeverity) => EditorWarning[]; /** @@ -95,6 +113,10 @@ export type EditorWarningRegistry = { // --| implemented logic |-- +/** + * the id to use for global editor warnings + * @type {string} + */ export const globalWarning = "GLOBAL_WARNINGS"; export function editorWarningRegistry(get: ZustandGet, set: ZustandSet) : EditorWarningRegistry { return { @@ -205,7 +227,11 @@ export function editorWarningRegistry(get: ZustandGet, set: ZustandSet) : Editor }} -// returns a summary of the warningRegistry + +/** + * returns a summary of the warningRegistry + * @returns {{info: number, warning: number, error: number, isValid: boolean}} + */ export function warningSummary() { const {severityIndex, isProgramValid} = useFlowStore.getState(); return { diff --git a/src/pages/VisProgPage/visualProgrammingUI/components/WarningSidebar.tsx b/src/pages/VisProgPage/visualProgrammingUI/components/WarningSidebar.tsx index 9e030e1..27a4684 100644 --- a/src/pages/VisProgPage/visualProgrammingUI/components/WarningSidebar.tsx +++ b/src/pages/VisProgPage/visualProgrammingUI/components/WarningSidebar.tsx @@ -9,6 +9,12 @@ import { } from "./EditorWarnings.tsx"; import styles from "./WarningSidebar.module.css"; +/** + * the warning sidebar, shows all warnings + * + * @returns {React.JSX.Element} + * @constructor + */ export function WarningsSidebar() { const warnings = useFlowStore.getState().getWarnings(); const [hide, setHide] = useState(false); @@ -72,6 +78,14 @@ export function WarningsSidebar() { ); } +/** + * the header of the warning sidebar, contains severity filtering buttons + * + * @param {WarningSeverity | "ALL"} severityFilter + * @param {(severity: (WarningSeverity | "ALL")) => void} onChange + * @returns {React.JSX.Element} + * @constructor + */ function WarningsHeader({ severityFilter, onChange, @@ -105,7 +119,13 @@ function WarningsHeader({ } - +/** + * the list of warnings in the warning sidebar + * + * @param {{warnings: EditorWarning[]}} props + * @returns {React.JSX.Element} + * @constructor + */ function WarningsList(props: { warnings: EditorWarning[] }) { const splitWarnings = { global: props.warnings.filter(w => w.scope.id === globalWarning), @@ -144,6 +164,13 @@ function WarningsList(props: { warnings: EditorWarning[] }) { ); } +/** + * a single warning in the warning sidebar + * + * @param {{warning: EditorWarning, key: string}} props + * @returns {React.JSX.Element} + * @constructor + */ function WarningListItem(props: { warning: EditorWarning, key: string}) { const jumpToNode = useJumpToNode(); @@ -163,6 +190,10 @@ function WarningListItem(props: { warning: EditorWarning, key: string}) { ); } +/** + * moves the editor to the provided node + * @returns {(nodeId: string) => void} + */ function useJumpToNode() { const { getNode, setCenter, getViewport } = useReactFlow(); const { addSelectedNodes } = useStoreApi().getState();