@ankorar/nodex 0.0.1 → 0.1.0

package/README.md

@@ -116,6 +116,20 @@ export function MindMapHydrator({ nodes }: { nodes: MindMapNode[] }) {
 }
 ```
 
+## Custom nodes (persisted)
+
+You can add **custom node types** that are stored and restored with the map.
+
+- Set `type: "custom"` and `customType: string` (e.g. `"note"`) on a node. Use `customPayload?: unknown` for app-specific data (e.g. `{ noteId: "..." }`).
+- These fields are part of `MindMapNode` and are **persisted** when your app saves the node tree (e.g. as `content` in your map API). When you load the map, pass the same tree into state so custom nodes keep their `customType` and `customPayload`.
+- Register a React component per `customType` via the `customNodeRenderers` prop on `Nodex`: `customNodeRenderers={{ note: NoteNodeComponent }}`. The component receives `CustomNodeProps` (`node`, style slots). Custom nodes are not auto-resized by layout (they keep the dimensions you set).
+
+```tsx
+<Nodex customNodeRenderers={{ note: NoteNode }}>
+  <Board>…</Board>
+</Nodex>
+```
+
 ## Styling
 
 `@ankorar/nodex` ships its own precompiled stylesheet, so consumer apps do not need to compile Tailwind classes from this package.
@@ -130,7 +144,7 @@ import "@ankorar/nodex/styles.css";
 
 ### Components
 
-- `Nodex`
+- `Nodex` (optional: `customNodeRenderers`, `nodeEditorCustomButtons`, `newNodesTextColor`)
 - `Board`
 - `Background`
 - `Nodes`
@@ -154,6 +168,9 @@ import "@ankorar/nodex/styles.css";
 
 - `useMindMapDebounce`
 - `useMindMapHistoryDebounce`
+- `useMindMapNode` (for custom node components: selection, addChild, destroy, getSide)
+- `useMindMapNodeMouseHandlers`
+- `useCustomNodeRenderers`
 
 ### State
 
@@ -163,11 +180,12 @@ import "@ankorar/nodex/styles.css";
 
 ### Types
 
-- `MindMapNode`
+- `MindMapNode` (includes optional `customType`, `customPayload` for custom nodes)
 - `MindMapNodeStyle`
-- `MindMapNodeType`
+- `MindMapNodeType` (`"default" | "central" | "image" | "custom"`)
 - `MindMapNodeTextAlign`
 - `MindMapNodeFontSize`
+- `CustomNodeProps`, `CustomNodeRenderers` (for custom node components)
 
 ## Package Structure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankorar/nodex",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/components/mindMap/Nodes.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties } from "react";
 import { useMindMapState } from "../../state/mindMap";
+import { useCustomNodeRenderers } from "../../contexts/CustomNodeRenderersContext";
 import { CentalNode } from "./CentalNode";
 import { DefaultNode } from "./DefaultNode";
 import { ImageNode } from "./ImageNode";
@@ -46,6 +47,7 @@ export function Nodes({
   imageNodeContentClassName,
   imageNodeContentStyle,
 }: NodesProps = {}) {
+  const { customNodeRenderers } = useCustomNodeRenderers();
   const { offset, scale, nodes, getFlatNodes } = useMindMapState(
     useShallow((state) => ({
       offset: state.offset,
@@ -97,6 +99,23 @@ export function Nodes({
             />
           );
         }
+        if (
+          node.type === "custom" &&
+          node.customType &&
+          customNodeRenderers[node.customType]
+        ) {
+          const CustomComponent = customNodeRenderers[node.customType];
+          return (
+            <CustomComponent
+              key={node.id}
+              node={node}
+              className={defaultNodeClassName}
+              style={defaultNodeStyle}
+              contentClassName={defaultNodeContentClassName}
+              contentStyle={defaultNodeContentStyle}
+            />
+          );
+        }
         return (
           <DefaultNode
             key={node.id}

package/src/components/mindMap/Nodex.tsx

@@ -7,6 +7,10 @@ import {
   MindMapNodeEditorProvider,
   type NodeEditorCustomButton,
 } from "../../contexts/MindMapNodeEditorContext";
+import {
+  CustomNodeRenderersProvider,
+  type CustomNodeRenderers,
+} from "../../contexts/CustomNodeRenderersContext";
 
 interface NodexProps {
   children?: ReactNode;
@@ -16,6 +20,8 @@ interface NodexProps {
   nodeEditorCustomButtons?: NodeEditorCustomButton[];
   /** Default text color for newly created nodes (Tab/Enter). E.g. "white" or "#ffffff" for dark backgrounds. */
   newNodesTextColor?: string | null;
+  /** Custom node renderers: map of customType string to component. Enables type "custom" nodes with customType key. */
+  customNodeRenderers?: CustomNodeRenderers;
 }
 
 export function Nodex({
@@ -24,6 +30,7 @@ export function Nodex({
   readOnly = false,
   nodeEditorCustomButtons,
   newNodesTextColor,
+  customNodeRenderers,
 }: NodexProps) {
   const setReadOnly = useMindMapState((state) => state.setReadOnly);
   const setNewNodesTextColor = useMindMapState(
@@ -51,15 +58,19 @@ export function Nodex({
 
   return (
     <MindMapNodeEditorProvider customButtons={nodeEditorCustomButtons ?? []}>
-      <section
-        data-nodex
-        className={cn(
-          "flex h-full min-h-[480px] w-full flex-col rounded-2xl bg-slate-50 text-slate-900 shadow-sm font-sans",
-          className,
-        )}
+      <CustomNodeRenderersProvider
+        customNodeRenderers={customNodeRenderers ?? {}}
       >
-        {children}
-      </section>
+        <section
+          data-nodex
+          className={cn(
+            "flex h-full min-h-[480px] w-full flex-col rounded-2xl bg-slate-50 text-slate-900 shadow-sm font-sans",
+            className,
+          )}
+        >
+          {children}
+        </section>
+      </CustomNodeRenderersProvider>
     </MindMapNodeEditorProvider>
   );
 }

package/src/contexts/CustomNodeRenderersContext.tsx

@@ -0,0 +1,63 @@
+import type { ComponentType } from "react";
+import type { CSSProperties } from "react";
+import {
+  type ReactNode,
+  createContext,
+  useContext,
+  useMemo,
+} from "react";
+import type { MindMapNode } from "../state/mindMap";
+
+/**
+ * Props passed to custom node components. Same style slots as built-in nodes.
+ */
+export interface CustomNodeProps {
+  node: MindMapNode;
+  className?: string;
+  style?: CSSProperties;
+  contentClassName?: string;
+  contentStyle?: CSSProperties;
+}
+
+/**
+ * Map of customType string -> React component to render that node.
+ * Register via Nodex customNodeRenderers prop.
+ */
+export type CustomNodeRenderers = Record<
+  string,
+  ComponentType<CustomNodeProps>
+>;
+
+type CustomNodeRenderersContextValue = {
+  customNodeRenderers: CustomNodeRenderers;
+};
+
+const defaultValue: CustomNodeRenderersContextValue = {
+  customNodeRenderers: {},
+};
+
+const CustomNodeRenderersContext =
+  createContext<CustomNodeRenderersContextValue>(defaultValue);
+
+export function CustomNodeRenderersProvider({
+  customNodeRenderers = {},
+  children,
+}: {
+  customNodeRenderers?: CustomNodeRenderers;
+  children: ReactNode;
+}) {
+  const value = useMemo(
+    () => ({ customNodeRenderers }),
+    [customNodeRenderers],
+  );
+
+  return (
+    <CustomNodeRenderersContext.Provider value={value}>
+      {children}
+    </CustomNodeRenderersContext.Provider>
+  );
+}
+
+export function useCustomNodeRenderers(): CustomNodeRenderersContextValue {
+  return useContext(CustomNodeRenderersContext);
+}

package/src/hooks/mindMap/useMindMapNodeEditor.ts

@@ -34,10 +34,40 @@ export function useMindMapNodeEditor({
 
   useLayoutEffect(() => {
     const element = textRef.current;
-    if (!element) {
+    if (!element || element.textContent === text) {
       return;
     }
-    if (!isEditing && element.textContent !== text) {
+
+    if (isEditing) {
+      const selection = window.getSelection();
+      let cursorOffset = 0;
+
+      if (selection && selection.rangeCount > 0) {
+        const range = selection.getRangeAt(0);
+        const preRange = document.createRange();
+        preRange.selectNodeContents(element);
+        preRange.setEnd(range.startContainer, range.startOffset);
+        cursorOffset = preRange.toString().length;
+      }
+
+      const oldLen = element.textContent?.length ?? 0;
+      const newLen = text.length;
+      const delta = newLen - oldLen;
+
+      element.textContent = text;
+
+      if (selection && element.firstChild) {
+        const adjustedOffset = Math.min(
+          Math.max(0, cursorOffset + delta),
+          newLen,
+        );
+        const range = document.createRange();
+        range.setStart(element.firstChild, adjustedOffset);
+        range.collapse(true);
+        selection.removeAllRanges();
+        selection.addRange(range);
+      }
+    } else {
       element.textContent = text;
     }
   }, [text, textRef, isEditing]);

package/src/index.ts

@@ -28,6 +28,8 @@ export {
   type ExportPdfOptions,
 } from "./utils/exportMindMapAsPdf";
 export { useMindMapHistoryDebounce } from "./hooks/mindMap/useMindMapHistoryDebounce";
+export { useMindMapNode } from "./hooks/mindMap/useMindMapNode";
+export { useMindMapNodeMouseHandlers } from "./hooks/mindMap/useMindMapNodeMouseHandlers";
 
 export { Background, type BackgroundProps } from "./components/mindMap/Background";
 export {
@@ -73,4 +75,12 @@ export type {
   MindMapNodeTextAlign,
   MindMapNodeFontSize,
 } from "./state/mindMap";
-export type { NodeEditorCustomButton } from "./contexts/MindMapNodeEditorContext";
+export type { NodeEditorCustomButton } from "./contexts/MindMapNodeEditorContext";
+export {
+  CustomNodeRenderersProvider,
+  useCustomNodeRenderers,
+} from "./contexts/CustomNodeRenderersContext";
+export type {
+  CustomNodeProps,
+  CustomNodeRenderers,
+} from "./contexts/CustomNodeRenderersContext";

package/src/state/mindMap.ts

@@ -2,7 +2,7 @@ import { create } from "zustand";
 
 export type MindMapNodeTextAlign = "left" | "center" | "right";
 export type MindMapNodeFontSize = 14 | 16 | 18 | 20 | 22 | 24;
-export type MindMapNodeType = "default" | "central" | "image";
+export type MindMapNodeType = "default" | "central" | "image" | "custom";
 
 export type MindMapNodeStyle = {
   w: number;
@@ -27,6 +27,10 @@ export type MindMapNode = {
   sequence: number;
   isVisible: boolean;
   childrens: MindMapNode[];
+  /** When type is "custom", identifies which custom renderer to use. */
+  customType?: string;
+  /** Optional payload for custom nodes (e.g. { noteId: string }). */
+  customPayload?: unknown;
 };
 
 interface UseMindMapState {
@@ -163,6 +167,8 @@ const cloneNodes = (nodes: MindMapNode[]): MindMapNode[] =>
     sequence: node.sequence,
     isVisible: node.isVisible,
     childrens: cloneNodes(node.childrens),
+    ...(node.customType != null && { customType: node.customType }),
+    ...(node.customPayload !== undefined && { customPayload: node.customPayload }),
   }));
 
 /**
@@ -209,7 +215,9 @@ function branchColorsEqual(a: MindMapNode[], b: MindMapNode[]): boolean {
 const PLACEHOLDER_W = 120;
 const PLACEHOLDER_H = 40;
 
-function getDefaultStyleForType(type: "central" | "default"): MindMapNodeStyle {
+function getDefaultStyleForType(
+  type: "central" | "default" | "custom",
+): MindMapNodeStyle {
   if (type === "central") {
     return {
       w: PLACEHOLDER_W,
@@ -245,7 +253,9 @@ function mergeMinimalStyle(nodes: MindMapNode[]): MindMapNode[] {
   const walk = (items: MindMapNode[]) => {
     for (const node of items) {
       if (node.type !== "image") {
-        const defaults = getDefaultStyleForType(node.type);
+        const styleType =
+          node.type === "custom" ? "default" : node.type;
+        const defaults = getDefaultStyleForType(styleType);
         node.style = {
           ...defaults,
           ...node.style,
@@ -425,7 +435,7 @@ const layoutNodes = (nodes: MindMapNode[]) => {
 const WRAP_WORDS_PER_LINE = 5;
 
 function applyMeasuredDimensionsToNode(node: MindMapNode): void {
-  if (node.type === "image") {
+  if (node.type === "image" || node.type === "custom") {
     return;
   }
   node.text = wrapTextAtWords(node.text ?? "", WRAP_WORDS_PER_LINE);
@@ -727,7 +737,7 @@ const useMindMapState = create<UseMindMapState>((set, get) => ({
 
     const { nodes } = get();
 
-    if (node.type !== "image") {
+    if (node.type !== "image" && node.type !== "custom") {
       const textSize = measureNodeText(node);
       const padding = node.style.padding;
       node.style.w = Math.max(8, textSize.w + padding.x * 2);