@ankorar/nodex 0.0.1

package/README.md

@@ -0,0 +1,228 @@
+# @ankorar/nodex
+
+Composable React package for building and extending a keyboard-driven mind map experience.
+
+This package exposes **state, hooks, and UI primitives** so each consumer app can build its own screen composition without being locked to a single page component.
+
+## What This Package Provides
+
+- Stateful mind map engine (Zustand-based)
+- Ready-to-compose visual components (board, nodes, minimap, popovers)
+- Keyboard and interaction handlers
+- Debounce hooks for history/state flow
+- Type exports for consumer-side extensions
+
+## Installation
+
+### Workspace (monorepo)
+
+```bash
+pnpm add @ankorar/nodex --workspace
+```
+
+### Future npm install
+
+```bash
+pnpm add @ankorar/nodex
+```
+
+## Quick Usage (Composition)
+
+```tsx
+import "@ankorar/nodex/styles.css";
+import {
+  Background,
+  Board,
+  MindMapHeader,
+  MineMap,
+  Nodex,
+  ZenCard,
+  useMindMapDebounce,
+} from "@ankorar/nodex";
+
+export function MindMapPage() {
+  useMindMapDebounce(() => undefined, { delayMs: 3000 });
+
+  return (
+    <section className="h-[calc(100dvh-11rem)] min-h-[38rem]">
+      <Nodex readOnly={false}>
+        <MindMapHeader title="Mind Map" />
+        <Board>
+          <Background />
+          <MineMap />
+          <ZenCard />
+        </Board>
+      </Nodex>
+    </section>
+  );
+}
+```
+
+## Read-only Mode
+
+Use `Nodex` with `readOnly` when the map should be visual-only:
+
+```tsx
+<Nodex readOnly>
+  <MindMapHeader title="Mind Map (View)" />
+  <Board>
+    <Background />
+    <MineMap />
+    <ZenCard />
+  </Board>
+</Nodex>
+```
+
+In `readOnly` mode, the package blocks content mutations (keyboard shortcuts, inline edits, add/remove node actions, and style popover updates).
+
+## High-quality image export
+
+You can export the whole map as a high-resolution PNG so that text stays readable when zooming, even on very large maps.
+
+- **From the header**: set `showExportImageButton` on `MindMapHeader` to show an “Export image” button that downloads a PNG (scale factor 3× by default).
+- **Programmatic**: use `exportMindMapAsHighQualityImage(nodes, options?)` with optional `scale` (1–4) and `filename`. Exported image dimensions are derived from node bounds plus padding, then multiplied by `scale`.
+
+```tsx
+import { MindMapHeader, exportMindMapAsHighQualityImage, useMindMapState } from "@ankorar/nodex";
+
+// In your page:
+<MindMapHeader title="My Map" showExportImageButton />
+
+// Or call manually:
+const nodes = useMindMapState.getState().getFlatNodes();
+await exportMindMapAsHighQualityImage(nodes, { scale: 3, filename: "my-map" });
+```
+
+## Initial State
+
+`@ankorar/nodex` now starts with an empty node list (`nodes: []`).
+
+If your app loads maps from an API, hydrate the state explicitly:
+
+```tsx
+import { useEffect } from "react";
+import { useMindMapState, type MindMapNode } from "@ankorar/nodex";
+
+export function MindMapHydrator({ nodes }: { nodes: MindMapNode[] }) {
+  useEffect(() => {
+    useMindMapState.setState({
+      nodes,
+      selectedNodeId: null,
+      editingNodeId: null,
+    });
+  }, [nodes]);
+
+  return null;
+}
+```
+
+## Styling
+
+`@ankorar/nodex` ships its own precompiled stylesheet, so consumer apps do not need to compile Tailwind classes from this package.
+
+Import it once at app entry:
+
+```tsx
+import "@ankorar/nodex/styles.css";
+```
+
+## Public API
+
+### Components
+
+- `Nodex`
+- `Board`
+- `Background`
+- `Nodes`
+- `Segments`
+- `CentalNode`
+- `DefaultNode`
+- `ImageNode`
+- `NodeStylePopover`
+- `KeyboardHelpDialog`
+- `MineMap`
+- `ZenCard`
+- `MindMapHeader` (optional: `showExportImageButton` for PNG export)
+
+### Utilities
+
+- `getMindMapPreviewDataUrl(nodes)` – data URL for minimap-style preview thumbnails
+- `exportMindMapAsHighQualityImage(nodes, options?)` – render map to high-resolution PNG and trigger download
+- `HIGH_QUALITY_EXPORT_SCALE` – default scale factor (3) for export
+
+### Hooks
+
+- `useMindMapDebounce`
+- `useMindMapHistoryDebounce`
+
+### State
+
+- `useMindMapState`
+- `useMindMapHistory`
+- `createMindMapSnapshot`
+
+### Types
+
+- `MindMapNode`
+- `MindMapNodeStyle`
+- `MindMapNodeType`
+- `MindMapNodeTextAlign`
+- `MindMapNodeFontSize`
+
+## Package Structure
+
+```text
+src/
+  components/
+    mindMap/
+    ui/
+  config/
+  handlers/
+  helpers/
+  hooks/
+    mindMap/
+  lib/
+  state/
+  index.ts
+```
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @ankorar/nodex dev
+```
+
+Available scripts in this package:
+
+- `dev`: watches types and regenerates `styles.css`
+- `build`: type validation + stylesheet build
+- `lint`: Type validation (`tsc --noEmit`)
+
+## Consumer Responsibilities
+
+Because this package is composition-first, the consumer app is responsible for:
+
+- Defining the route/page shell
+- Providing app-level layout and authentication wrappers
+- Loading global styles/tokens expected by the selected UI setup
+
+## Versioning and Publishing
+
+Before publishing a new version:
+
+1. Validate exports in `src/index.ts`.
+2. Run package checks:
+   - `pnpm --filter @ankorar/nodex build`
+   - `pnpm --filter @ankorar/nodex lint`
+3. Update docs for any API/behavior change.
+4. Bump package version in `packages/nodex/package.json`.
+
+## Documentation Policy
+
+All package documentation must be written in **English**.
+
+For mandatory documentation rules (including AI/chat workflows), see:
+
+- `docs/AI_DOCUMENTATION_POLICY.md`

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ankorar/nodex",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "files": [
+    "src",
+    "styles.css"
+  ],
+  "peerDependencies": {
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  },
+  "dependencies": {
+    "@radix-ui/react-dialog": "1.1.15",
+    "@radix-ui/react-popover": "1.1.15",
+    "@radix-ui/react-select": "2.2.6",
+    "@radix-ui/react-toggle": "1.1.10",
+    "@radix-ui/react-toggle-group": "1.1.11",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "contrast": "1.0.1",
+    "jspdf": "2.5.2",
+    "lucide-react": "0.562.0",
+    "tailwind-merge": "3.4.0",
+    "zustand": "5.0.9"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "4.1.0",
+    "@types/react": "19.2.5",
+    "@types/react-dom": "19.2.3",
+    "concurrently": "8.2.2",
+    "tailwindcss": "4.1.0",
+    "tw-animate-css": "1.4.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "dev": "concurrently \"pnpm run dev:types\" \"pnpm run dev:styles\"",
+    "dev:types": "tsc --watch --preserveWatchOutput --noEmit",
+    "dev:styles": "tailwindcss -i ./src/styles.input.css -o ./styles.css --watch",
+    "build": "pnpm run build:types && pnpm run build:styles",
+    "build:types": "tsc --noEmit",
+    "build:styles": "tailwindcss -i ./src/styles.input.css -o ./styles.css --minify",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/components/mindMap/Background.tsx

@@ -0,0 +1,39 @@
+import type { CSSProperties } from "react";
+
+import { useMindMapState } from "../../state/mindMap";
+import { useShallow } from "zustand/react/shallow";
+import { cn } from "../../lib/utils";
+
+export interface BackgroundProps {
+  /** Classes CSS adicionais; quando passado, o fundo padrão (bg-slate-50) não é aplicado, permitindo estilização coerente com a aplicação */
+  className?: string;
+  /** Estilos inline; mesclado após os estilos internos (grid, offset), permitindo sobrescrever cor de fundo, grid etc. */
+  style?: CSSProperties;
+}
+
+const GRID_SIZE = 40;
+
+export function Background({ className, style }: BackgroundProps = {}) {
+  const { offset, scale } = useMindMapState(
+    useShallow((state) => ({
+      offset: state.offset,
+      scale: state.scale,
+    })),
+  );
+  const gridSizePx = GRID_SIZE * scale;
+
+  return (
+    <div
+      className={cn("absolute inset-0", className ?? "bg-slate-50")}
+      style={
+        {
+          backgroundImage:
+            "radial-gradient(rgba(148, 163, 184, 0.45) 1px, transparent 1px)",
+          backgroundSize: `${gridSizePx}px ${gridSizePx}px`,
+          backgroundPosition: `${offset.x}px ${offset.y}px`,
+          ...style,
+        } as CSSProperties
+      }
+    />
+  );
+}

package/src/components/mindMap/Board.tsx

@@ -0,0 +1,159 @@
+import type { CSSProperties } from "react";
+import { useRootMouseHandlers } from "../../hooks/mindMap/useRootMouseHandlers";
+import { useMindMapHistoryDebounce } from "../../hooks/mindMap/useMindMapHistoryDebounce";
+import { useUpdateCenter } from "../../hooks/mindMap/useUpdateCenter";
+import { useMindMapState } from "../../state/mindMap";
+import { type ReactNode, useEffect, useRef } from "react";
+import { Nodes } from "./Nodes";
+import {
+  NodeStylePopover,
+  type NodeStylePopoverStyleSlots,
+} from "./NodeStylePopover";
+import { KeyboardHelpDialog } from "./KeyboardHelpDialog";
+import { cn } from "../../lib/utils";
+
+/** Slots para estilizar o Board, nós, barra de edição e modal de ajuda */
+export interface BoardStyleSlots extends NodeStylePopoverStyleSlots {
+  /** Raiz do board */
+  className?: string;
+  style?: CSSProperties;
+  /** Container dos nós (área com transform scale/offset) */
+  nodesWrapperClassName?: string;
+  nodesWrapperStyle?: CSSProperties;
+  /** Nó central */
+  centralNodeClassName?: string;
+  centralNodeStyle?: CSSProperties;
+  centralNodeContentClassName?: string;
+  centralNodeContentStyle?: CSSProperties;
+  /** Nó padrão (ramo) */
+  defaultNodeClassName?: string;
+  defaultNodeStyle?: CSSProperties;
+  defaultNodeContentClassName?: string;
+  defaultNodeContentStyle?: CSSProperties;
+  /** Nó de imagem */
+  imageNodeClassName?: string;
+  imageNodeStyle?: CSSProperties;
+  imageNodeContentClassName?: string;
+  imageNodeContentStyle?: CSSProperties;
+  /** Modal de ajuda (Alt+H): conteúdo do diálogo */
+  helpDialogContentClassName?: string;
+  helpDialogContentStyle?: CSSProperties;
+  /** Modal de ajuda: título */
+  helpDialogTitleClassName?: string;
+  /** Modal de ajuda: descrição */
+  helpDialogDescriptionClassName?: string;
+  /** Modal de ajuda: cada linha de atalho */
+  helpDialogItemClassName?: string;
+  /** Modal de ajuda: badge da tecla */
+  helpDialogShortcutKeyClassName?: string;
+  /** Modal de ajuda: texto da descrição do atalho */
+  helpDialogShortcutDescriptionClassName?: string;
+}
+
+export interface BoardProps extends BoardStyleSlots {
+  children?: ReactNode;
+  /** Optional array of colors applied by branch: each direct child of the central node gets a color, and all its descendants keep the same color. */
+  segmentColors?: string[];
+}
+
+export function Board({
+  children,
+  className,
+  style,
+  nodesWrapperClassName,
+  nodesWrapperStyle,
+  centralNodeClassName,
+  centralNodeStyle,
+  centralNodeContentClassName,
+  centralNodeContentStyle,
+  defaultNodeClassName,
+  defaultNodeStyle,
+  defaultNodeContentClassName,
+  defaultNodeContentStyle,
+  imageNodeClassName,
+  imageNodeStyle,
+  imageNodeContentClassName,
+  imageNodeContentStyle,
+  contentClassName: nodeStylePopoverContentClassName,
+  contentStyle: nodeStylePopoverContentStyle,
+  buttonClassName: nodeStylePopoverButtonClassName,
+  buttonStyle: nodeStylePopoverButtonStyle,
+  toggleItemClassName: nodeStylePopoverToggleItemClassName,
+  selectTriggerClassName: nodeStylePopoverSelectTriggerClassName,
+  selectContentClassName: nodeStylePopoverSelectContentClassName,
+  textColors: nodeStylePopoverTextColors,
+  backgroundColors: nodeStylePopoverBackgroundColors,
+  segmentColors,
+  helpDialogContentClassName,
+  helpDialogContentStyle,
+  helpDialogTitleClassName,
+  helpDialogDescriptionClassName,
+  helpDialogItemClassName,
+  helpDialogShortcutKeyClassName,
+  helpDialogShortcutDescriptionClassName,
+}: BoardProps) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const applySegmentColors = useMindMapState((s) => s.applySegmentColors);
+  const nodes = useMindMapState((s) => s.nodes);
+
+  const { ...mouseHandlers } = useRootMouseHandlers({
+    rootRef,
+  });
+
+  useUpdateCenter({ rootRef });
+  useMindMapHistoryDebounce({ delayMs: 3000 });
+
+  useEffect(() => {
+    if (segmentColors?.length) {
+      applySegmentColors(segmentColors);
+    }
+  }, [segmentColors, applySegmentColors, nodes]);
+
+  return (
+    <div
+      data-nodex-root
+      className={cn("relative flex-1 overflow-hidden cursor-grab", className)}
+      style={style}
+      ref={rootRef}
+      {...mouseHandlers}
+    >
+      {children}
+      <KeyboardHelpDialog
+        contentClassName={helpDialogContentClassName}
+        contentStyle={helpDialogContentStyle}
+        titleClassName={helpDialogTitleClassName}
+        descriptionClassName={helpDialogDescriptionClassName}
+        itemClassName={helpDialogItemClassName}
+        shortcutKeyClassName={helpDialogShortcutKeyClassName}
+        shortcutDescriptionClassName={helpDialogShortcutDescriptionClassName}
+      />
+      <NodeStylePopover
+        contentClassName={nodeStylePopoverContentClassName}
+        contentStyle={nodeStylePopoverContentStyle}
+        buttonClassName={nodeStylePopoverButtonClassName}
+        buttonStyle={nodeStylePopoverButtonStyle}
+        toggleItemClassName={nodeStylePopoverToggleItemClassName}
+        selectTriggerClassName={nodeStylePopoverSelectTriggerClassName}
+        selectContentClassName={nodeStylePopoverSelectContentClassName}
+        textColors={nodeStylePopoverTextColors}
+        backgroundColors={nodeStylePopoverBackgroundColors}
+      />
+      <Nodes
+        nodesWrapperClassName={nodesWrapperClassName}
+        nodesWrapperStyle={nodesWrapperStyle}
+        centralNodeClassName={centralNodeClassName}
+        centralNodeStyle={centralNodeStyle}
+        centralNodeContentClassName={centralNodeContentClassName}
+        centralNodeContentStyle={centralNodeContentStyle}
+        defaultNodeClassName={defaultNodeClassName}
+        defaultNodeStyle={defaultNodeStyle}
+        defaultNodeContentClassName={defaultNodeContentClassName}
+        defaultNodeContentStyle={defaultNodeContentStyle}
+        imageNodeClassName={imageNodeClassName}
+        imageNodeStyle={imageNodeStyle}
+        imageNodeContentClassName={imageNodeContentClassName}
+        imageNodeContentStyle={imageNodeContentStyle}
+      />
+    </div>
+  );
+}

package/src/components/mindMap/CentalNode.tsx

@@ -0,0 +1,121 @@
+import type { CSSProperties } from "react";
+import type { MindMapNode } from "../../state/mindMap";
+import { useRef } from "react";
+import { useMindMapState } from "../../state/mindMap";
+import { useShallow } from "zustand/react/shallow";
+import { useMindMapNodeMouseHandlers } from "../../hooks/mindMap/useMindMapNodeMouseHandlers";
+import { useMindMapNode } from "../../hooks/mindMap/useMindMapNode";
+import { useMindMapNodeEditor } from "../../hooks/mindMap/useMindMapNodeEditor";
+import { cn } from "../../lib/utils";
+
+interface CentalNodeProps {
+  node: MindMapNode;
+  className?: string;
+  style?: CSSProperties;
+  /** Caixa do conteúdo (círculo com texto) */
+  contentClassName?: string;
+  contentStyle?: CSSProperties;
+}
+
+export function CentalNode({
+  node,
+  className,
+  style,
+  contentClassName,
+  contentStyle,
+}: CentalNodeProps) {
+  const { editingNodeId, selectedNodeId, readOnly } = useMindMapState(
+    useShallow((state) => ({
+      selectedNodeId: state.selectedNodeId,
+      editingNodeId: state.editingNodeId,
+      readOnly: state.readOnly,
+    })),
+  );
+
+  const textRef = useRef<HTMLSpanElement | null>(null);
+  const { node: logicalNode } = useMindMapNode({ nodeId: node.id });
+  const { onMouseDown, onDoubleClick } = useMindMapNodeMouseHandlers(node.id);
+  const editableHandlers = useMindMapNodeEditor({
+    nodeId: node.id,
+    text: node.text,
+    textRef,
+  });
+
+  return (
+    <div
+      className={cn("group absolute", className)}
+      data-nodex-node
+      style={{
+        transform: `translate(${node.pos.x}px, ${node.pos.y}px)`,
+        width: node.style.w + node.style.wrapperPadding * 2,
+        height: node.style.h + node.style.wrapperPadding * 2,
+        ...style,
+      }}
+      onMouseDown={onMouseDown}
+      onDoubleClick={onDoubleClick}
+    >
+      <div
+        className="relative h-full w-full"
+        style={{ padding: node.style.wrapperPadding }}
+      >
+        <div
+          data-bold={node.style.isBold}
+          data-italic={node.style.isItalic}
+          className={cn(
+            "flex items-center justify-center rounded-full border border-slate-300 bg-white text-slate-900 shadow-sm data-[bold=true]:font-bold data-[italic=true]:italic",
+            editingNodeId === node.id ? "select-text" : "select-none",
+            contentClassName,
+          )}
+          style={{
+            ...contentStyle,
+            width: node.style.w,
+            height: node.style.h,
+            padding: `${node.style.padding.y}px ${node.style.padding.x}px`,
+            borderColor: node.style.color,
+            fontSize: node.style.fontSize,
+            textAlign: node.style.textAlign,
+            boxShadow:
+              selectedNodeId === node.id
+                ? `0 0 0 3px ${node.style.color}`
+                : undefined,
+            color: node.style.textColor,
+            backgroundColor: node.style.backgroundColor,
+          }}
+          onDoubleClick={onDoubleClick}
+        >
+          <span
+            ref={textRef}
+            className="whitespace-pre outline-none leading-none"
+            contentEditable={!readOnly && editingNodeId === node.id}
+            suppressContentEditableWarning
+            onMouseDown={(event) => {
+              if (event.detail > 1) {
+                event.preventDefault();
+              }
+            }}
+            {...editableHandlers}
+          />
+        </div>
+      </div>
+
+      <button
+        type="button"
+        data-selected={selectedNodeId === node.id}
+        data-editing={editingNodeId === node.id}
+        data-read-only={readOnly}
+        className="absolute data-[read-only=false]:data-[selected=true]:data-[editing=false]:flex hidden -right-3 top-1/2 h-6 w-6 -translate-y-1/2 items-center justify-center rounded-full border border-slate-300 bg-white text-sm font-bold text-slate-700 shadow-sm transition"
+        style={{ borderColor: node.style.color, color: node.style.color }}
+        onMouseDown={(event) => {
+          event.stopPropagation();
+        }}
+        onClick={(event) => {
+          event.stopPropagation();
+          logicalNode?.addChild();
+        }}
+        aria-label="Adicionar node"
+      >
+        +
+      </button>
+    </div>
+  );
+}