Feat/documentation

[SorsOps]

PR Type

Enhancement, Documentation

---

Description

• Enhanced Node class with new methods and improved type safety.
• Updated various node types to use new naming conventions and added example JSON documentation.
• Added Mixpanel script for analytics in the UI.
• Refactored several components for better handling of annotations and descriptions.
• Enhanced Subgraph and ArraySubgraph nodes to handle updates from inner graphs.

---

Changes walkthrough 📝

	Relevant files
Enhancement	8 files node.ts Enhance Node class with new methods and type safety improvements packages/graph-engine/src/programmatic/node.ts Added new methods: setAnnotation, removeInput, removeOutput. Changed type annotations from any to unknown. Added getAllOutputs method. +40/-20  graph.tsx Update graph editor with new constants and initial graph loading packages/graph-editor/src/editor/graph.tsx Updated imports and removed unused updateEdge. Added constants NOTE and PASSTHROUGH. Added useEffect to load initial graph. +22/-12  _document.tsx Add Mixpanel script for analytics                                                packages/ui/src/pages/_document.tsx Added Mixpanel script for analytics. +13/-1    noteNode.tsx Refactor NoteNode component for better description handling packages/graph-editor/src/components/flow/nodes/noteNode.tsx Refactored NoteNode component to use a wrapper and handle description changes. +27/-57  index.tsx Update NodeSettings component for better annotation handling packages/graph-editor/src/components/panels/nodeSettings/index.tsx Updated NodeSettings component to handle annotations and description changes. +14/-14  subgraph.ts Enhance Subgraph node with autorun for inner graph updates packages/graph-engine/src/nodes/generic/subgraph.ts Added autorun to handle updates from the inner graph. Added logic to update outputs when the inner graph changes. +32/-11  nodeV2.tsx Update NodeWrap component for better value handling and UI packages/graph-editor/src/components/flow/wrapper/nodeV2.tsx Updated NodeWrap component to handle different value types. Added style adjustments for better UI. +9/-6      arraySubgraph.ts Update ArraySubgraph node type and improve type safety      packages/graph-engine/src/nodes/array/arraySubgraph.ts Changed input node type to studio.tokens.generic.input. Added eslint-disable comments for type safety. +4/-5
Documentation	7 files constant.ts Update Constant node type and add example documentation    packages/graph-engine/src/nodes/generic/constant.ts Changed node type to studio.tokens.generic.constant. Added example JSON documentation. +12/-4    input.ts Update Input node type, add example, and enhance deserialization packages/graph-engine/src/nodes/generic/input.ts Changed node type to studio.tokens.generic.input. Added example JSON documentation. Added deserialize method to create outputs immediately. +48/-17  addVariadic.ts Update Add Variadic node type and add example documentation packages/graph-engine/src/nodes/math/addVariadic.ts Changed node type to studio.tokens.math.addVariadic. Added example JSON documentation. +8/-2      add.ts Update Add node type and add example documentation              packages/graph-engine/src/nodes/math/add.ts Changed node type to studio.tokens.math.add. Added example JSON documentation. +8/-2      panic.ts Update Panic node type and add example documentation          packages/graph-engine/src/nodes/generic/panic.ts Changed node type to studio.tokens.generic.panic. Added example JSON documentation. +10/-9    output.ts Update Output node type and enhance deserialization            packages/graph-engine/src/nodes/generic/output.ts Changed node type to studio.tokens.generic.output. Added deserialize method to create outputs immediately. +38/-16  abs.ts Update Absolute node type and add example documentation    packages/graph-engine/src/nodes/math/abs.ts Changed node type to studio.tokens.math.abs. Added example JSON documentation. +8/-2

---

💡 PR-Agent usage:
Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[changeset-bot]

⚠️ No Changeset found

Latest commit: ef93e5d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

PR Reviewer Guide 🔍

⏱️ Estimated effort to review [1-5]	4
🧪 Relevant tests	No
🔒 Security concerns	- Mixpanel Script Injection: The PR includes the injection of a Mixpanel script directly via an inline script in `_document.tsx`. Review the content of the script to ensure there are no security vulnerabilities such as XSS. Also, confirm that the Mixpanel initialization is correctly configured and that the API key is securely handled.
⚡ Key issues to review	Type Safety Improvements: The PR includes changes from any to unknown for better type safety in TypeScript. This is generally a positive change, enhancing the robustness of the code. However, it's crucial to ensure that all related functions and methods that interact with these types are properly updated to handle the unknown type correctly.
	New Methods in Node Class: New methods such as setAnnotation, removeInput, and removeOutput have been added. It's important to review these methods for correct functionality and to check if they properly manage the state and lifecycle of the node, especially in a graph context.
	MobX State Management: The use of MobX for state management in node.ts has been expanded with new observable actions. Review is needed to ensure that state mutations are handled correctly and that there are no unintended side effects or performance issues.
	Mixpanel Integration: The addition of Mixpanel for analytics raises concerns about potential privacy issues and the security of the implementation. Ensure that the API key is not exposed in the codebase and that data collection complies with privacy regulations.
	Documentation and Examples: Several JSON examples have been added across various files. Verify that these examples are accurate and effectively demonstrate the use of the associated functionality.
	Code Cleanup and Refactoring: The PR includes significant refactoring and removal of unused imports. Ensure that these changes do not affect existing functionalities and that all dependencies are correctly managed.

[github-actions]

PR Code Suggestions ✨

Category	Suggestion	Score
Error handling	Implement error handling for color creation to manage invalid inputs Add error handling for potential exceptions when creating new Color instances, as invalid color values can cause runtime errors. packages/graph-engine/src/nodes/color/contrasting.ts [95-97] -const colorA = new Color(a); -const colorB = new Color(b); -const backgroundCol = new Color(background); +let colorA, colorB, backgroundCol; +try { + colorA = new Color(a); + colorB = new Color(b); + backgroundCol = new Color(background); +} catch (error) { + console.error("Invalid color input:", error); +} Suggestion importance[1-10]: 10 Why: Adding error handling for the creation of new Color instances is crucial to prevent runtime errors due to invalid color values. This enhances the robustness and reliability of the code.	10
Best practice	Use a state hook to manage the textarea's value and update the node's annotation in an effect Replace the direct mutation of the node's annotation within the onChange handler with a more controlled approach using a state hook to manage the textarea's value. This ensures that the component's state is the single source of truth and can help prevent potential issues with asynchronous state updates. packages/graph-editor/src/components/flow/nodes/noteNode.tsx [32-34] -const onChange = (str)=>{ - node.setAnnotation(description, str); -} +const [text, setText] = useState(node.getAnnotation(description)); +const onChange = (str) => { + setText(str); +}; +useEffect(() => { + node.setAnnotation(description, text); +}, [text]); Suggestion importance[1-10]: 9 Why: This suggestion improves the code by ensuring that the component's state is the single source of truth, which can prevent potential issues with asynchronous state updates. It is a best practice for managing state in React components.	9
	Use strict equality check to avoid type coercion Ensure that the wcag variable is checked for strict equality using === instead of == to avoid potential type coercion issues which could lead to unexpected behavior. packages/graph-engine/src/nodes/color/contrasting.ts [99] -if (wcag == WcagVersion.V2) { +if (wcag === WcagVersion.V2) { Suggestion importance[1-10]: 9 Why: Using strict equality (===) instead of loose equality (==) is a best practice in JavaScript/TypeScript to avoid potential type coercion issues, which can lead to unexpected behavior. This is a significant improvement for code reliability.	9
	Use class methods for state updates to ensure immutability and reactivity The NodeDescription component should use a more robust method to update annotations. Instead of directly modifying the annotations object, consider using a method provided by the Node class that ensures immutability and reactivity. packages/graph-editor/src/components/panels/nodeSettings/index.tsx [102] -selectedNode.setAnnotation(description, newString); +selectedNode.updateAnnotation(description, newString); Suggestion importance[1-10]: 7 Why: This suggestion improves code maintainability and ensures that state updates are handled in a more controlled manner, although it is more of a best practice than a critical fix.	7
Possible bug	Ensure safe access to potentially undefined properties The NodeSettings component is directly accessing the annotations property of selectedNode which might be undefined. It's safer to provide a fallback value or check for the existence of annotations before accessing it. packages/graph-editor/src/components/panels/nodeSettings/index.tsx [34] -<NodeSettings selectedNode={selectedNode} annotations={selectedNode.annotations} key={nodeID} /> +<NodeSettings selectedNode={selectedNode} annotations={selectedNode.annotations || {}} key={nodeID} /> Suggestion importance[1-10]: 9 Why: This suggestion addresses a potential runtime error by ensuring that the annotations property is safely accessed, which is crucial for preventing crashes.	9
	Add bounds checking for the index to prevent out-of-bounds errors Add a check to ensure that the index is within the bounds of the array to prevent runtime errors. packages/graph-engine/src/nodes/array/indexArray.ts [13-18] array: T[] index: number +if (index < 0 || index >= array.length) throw new Error("Index out of bounds"); Suggestion importance[1-10]: 9 Why: Adding bounds checking for the index is crucial to prevent runtime errors, making this a highly valuable improvement.	9
	Add null checks to prevent rendering errors The OutputSheetObserver component should handle the case where node might be undefined to prevent runtime errors in the rendering process. packages/graph-editor/src/components/panels/output/index.tsx [19] -return <OutputSheetObserver node={selectedNode} />; +return selectedNode ? <OutputSheetObserver node={selectedNode} /> : null; Suggestion importance[1-10]: 8 Why: This suggestion prevents potential runtime errors by adding a null check, which is important for the stability of the application.	8
	Check for null values before using them to prevent runtime errors When creating a new node of type PASSTHROUGH, it's important to ensure that the graph object is correctly initialized and not null to avoid runtime errors. packages/graph-editor/src/editor/graph.tsx [609-611] -const newNode = new fullNodeLookup[PASSTHROUGH]({ - graph -}); +if (graph) { + const newNode = new fullNodeLookup[PASSTHROUGH]({ + graph + }); + // additional logic here +} Suggestion importance[1-10]: 8 Why: This suggestion helps prevent runtime errors by ensuring that the graph object is not null before it is used, which is a good practice for robust code.	8
	Correct the spacing in the input property name to ensure consistency Ensure consistent spacing around the added input property name to avoid potential issues in frameworks or tools that may parse the input keys strictly. packages/graph-engine/src/nodes/array/arraySubgraph.ts [30] -input.addInput("value ", { +input.addInput("value", { Suggestion importance[1-10]: 8 Why: Ensuring consistent spacing in property names is important to avoid potential parsing issues, making this a valuable correction.	8
Enhancement	Validate the input name to prevent empty or duplicate names before adding a new input Add a validation check for inputName before creating a new input to ensure that the input name is not empty or duplicated, which could lead to runtime errors or logical issues in the application. packages/graph-editor/src/components/panels/inputs/dynamicInputs.tsx [42-44] -const input = node.addInput(inputName, { - type, - visible: node.nodeType() !== "studio.tokens.generic.input", -}); +if (inputName.trim() && !node.inputs.some(input => input.name === inputName)) { + const input = node.addInput(inputName, { + type, + visible: node.nodeType() !== "studio.tokens.generic.input", + }); +} else { + console.error("Invalid or duplicate input name"); +} Suggestion importance[1-10]: 8 Why: This suggestion enhances the code by adding validation to prevent empty or duplicate input names, which can prevent runtime errors and logical issues.	8
	Add a default value for the correctionFactor input Consider adding a default value for the correctionFactor input to ensure that the node behaves predictably even if the input is not explicitly provided by the user. packages/graph-engine/src/nodes/accessibility/baseFontSize.ts [14] -correctionFactor: number; +correctionFactor: number = 1.0; // Default value as an example Suggestion importance[1-10]: 7 Why: Adding a default value for correctionFactor is a good enhancement for predictability, but it is not crucial for functionality.	7
Possible issue	Ensure error handling in the component by checking the existence of an error before rendering Add a conditional rendering to handle the case where the error prop might be null. This prevents potential issues in the rendering process where an error state is expected but not present. packages/graph-editor/src/components/flow/wrapper/node.tsx [84-85] -<NodeWrapper error={Boolean(error)} className={error ? 'error' : ''}> +<NodeWrapper error={!!error} className={error ? 'error' : ''}> Suggestion importance[1-10]: 7 Why: This suggestion improves error handling by ensuring that the error prop is checked for null values before rendering, which can prevent potential rendering issues.	7
Maintainability	Use styled components for consistent and reusable styles Replace the inline CSS in the JSX with a styled component or use a CSS module to improve maintainability and reusability of styles across components. packages/graph-editor/src/components/flow/wrapper/node.tsx [86-93] -<Stack - direction="column" - gap={0} - css={{flex:1}} - onClick={onClick} - {...rest} -> +const StyledStack = styled(Stack, { + flex: 1, + direction: 'column', + gap: 0 +}); +<StyledStack onClick={onClick} {...rest} /> Suggestion importance[1-10]: 6 Why: This suggestion improves maintainability and reusability of styles by replacing inline CSS with styled components, which is a good practice for consistent styling across components.	6
	Split grouped imports into individual lines for clarity Refactor the import statements to use a single line for each import to enhance code readability and maintainability. packages/graph-engine/src/nodes/color/contrasting.ts [3-6] -import { - BooleanSchema, - ColorSchema, - NumberSchema, - StringSchema, -} from "../../schemas/index.js"; +import { BooleanSchema } from "../../schemas/index.js"; +import { ColorSchema } from "../../schemas/index.js"; +import { NumberSchema } from "../../schemas/index.js"; +import { StringSchema } from "../../schemas/index.js"; Suggestion importance[1-10]: 6 Why: While splitting grouped imports into individual lines can improve readability and maintainability, it is a minor stylistic change and does not significantly impact the functionality or performance of the code.	6
	Use let instead of const for color variables to allow modifications Replace the const declarations with let for color and background to allow potential modifications in future extensions of the method. packages/graph-engine/src/nodes/accessibility/contrast.ts [42-43] -const color = new Color(a); -const background = new Color(b); +let color = new Color(a); +let background = new Color(b); Suggestion importance[1-10]: 3 Why: The current use of const is appropriate as there are no modifications to the variables. Changing to let is unnecessary and could reduce code clarity.	3