React + Vite

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

Currently, two official plugins are available:

• @vitejs/plugin-react uses Babel for Fast Refresh
• @vitejs/plugin-react-swc uses SWC for Fast Refresh

Expanding the ESLint configuration

If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the TS template for information on how to integrate TypeScript and typescript-eslint in your project.

Roadmap Builder

A flexible React component library for building and displaying interactive roadmaps.

Installation

npm install roadmap-builder
# or
yarn add roadmap-builder

Features

• Interactive roadmap display with customizable components
• Visual roadmap builder tool
• Support for different path types (horizontal, vertical, diagonal)
• Customizable level and path components
• Progress tracking with completed/future states

Usage

Displaying a Roadmap

import React from "react";
import { RoadmapViewer } from "roadmap-builder";

// Custom components
const CompletedLevelComponent = ({ content, onClick }) => (
  <button
    onClick={onClick}
    style={{
      /* Your styles here */
      background: "green",
      color: "white",
      borderRadius: "50%",
    }}
  >
    {content}
  </button>
);

const FutureLevelComponent = ({ content, onClick }) => (
  <button
    onClick={onClick}
    style={{
      /* Your styles here */
      background: "blue",
      color: "white",
      borderRadius: "50%",
    }}
  >
    {content}
  </button>
);

// Path components
const pathComponents = {
  horizontal: <YourHorizontalPathComponent />,
  vertical: <YourVerticalPathComponent />,
  diagonalRightDown: <YourDiagonalRightDownComponent />,
  diagonalLeftDown: <YourDiagonalLeftDownComponent />,
};

// Completed path components
const completedPathComponents = {
  horizontal: <YourCompletedHorizontalPathComponent />,
  vertical: <YourCompletedVerticalPathComponent />,
  diagonalRightDown: <YourCompletedDiagonalRightDownComponent />,
  diagonalLeftDown: <YourCompletedDiagonalLeftDownComponent />,
};

// Example roadmap positions
const positions = {
  "level-1": {
    x: 1,
    y: 0,
    type: "level",
    status: "completed",
    levelContent: "1",
    order: 1,
  },
  "path-1-2": {
    x: 1,
    y: 1,
    type: "path",
    status: "completed",
    pathComponent: "vertical",
  },
  "level-2": {
    x: 1,
    y: 2,
    type: "level",
    status: "completed",
    levelContent: "2",
    order: 2,
  },
  // Add more positions as needed
};

function App() {
  const handleLevelClick = (order) => {
    console.log(`Level ${order} clicked`);
  };

  return (
    <RoadmapViewer
      matrixWidth={5}
      matrixHeight={9}
      positions={positions}
      pathComponents={pathComponents}
      completedPathComponents={completedPathComponents}
      completedLevelComponent={<CompletedLevelComponent />}
      futureLevelComponent={<FutureLevelComponent />}
      onLevelClick={handleLevelClick}
      cellWidth={80}
      cellHeight={80}
    />
  );
}

Using the Roadmap Builder

import React, { useState } from "react";
import { RoadmapBuilder, RoadmapViewer } from "roadmap-builder";

function App() {
  const [positions, setPositions] = useState({});

  // Define your custom components
  const pathComponents = {
    horizontal: <YourHorizontalPathComponent />,
    vertical: <YourVerticalPathComponent />,
    // ...
  };

  const completedPathComponents = {
    horizontal: <YourCompletedHorizontalPathComponent />,
    vertical: <YourCompletedVerticalPathComponent />,
    // ...
  };

  const handleSave = (newPositions) => {
    setPositions(newPositions);
    // You can also save these positions to your backend or local storage
  };

  return (
    <div>
      <RoadmapBuilder
        initialMatrixWidth={5}
        initialMatrixHeight={9}
        initialPositions={positions}
        pathComponents={pathComponents}
        completedPathComponents={completedPathComponents}
        completedLevelComponent={<YourCompletedLevelComponent />}
        futureLevelComponent={<YourFutureLevelComponent />}
        cellWidth={80}
        cellHeight={80}
        onSave={handleSave}
      />

      {/* You can display the roadmap with the saved positions */}
      <RoadmapViewer
        matrixWidth={5}
        matrixHeight={9}
        positions={positions}
        pathComponents={pathComponents}
        completedPathComponents={completedPathComponents}
        completedLevelComponent={<YourCompletedLevelComponent />}
        futureLevelComponent={<YourFutureLevelComponent />}
        onLevelClick={(order) => console.log(`Level ${order} clicked`)}
        cellWidth={80}
        cellHeight={80}
      />
    </div>
  );
}

API Reference

RoadmapViewer Props

| Prop | Type | Required | Description | | ------------------------- | -------- | -------- | ---------------------------------------------------------------------------- | | matrixWidth | number | Yes | Width of the matrix grid | | matrixHeight | number | Yes | Height of the matrix grid | | positions | object | Yes | Object containing positions and properties of levels and paths | | pathComponents | object | Yes | Components to render for different path types | | completedPathComponents | object | Yes | Components to render for completed path types | | completedLevelComponent | element | Yes | Component to render for completed levels | | futureLevelComponent | element | Yes | Component to render for future levels | | onLevelClick | function | No | Callback function when a level is clicked, receives level order as parameter | | cellWidth | number | No | Width of each matrix cell in pixels (default: 100) | | cellHeight | number | No | Height of each matrix cell in pixels (default: 100) | | cellGap | number | No | Gap between cells in pixels (default: 0) |

RoadmapBuilder Props

| Prop | Type | Required | Description | | ------------------------- | -------- | -------- | -------------------------------------------------- | | initialMatrixWidth | number | No | Initial width of the matrix grid (default: 5) | | initialMatrixHeight | number | No | Initial height of the matrix grid (default: 9) | | initialPositions | object | No | Initial positions for the builder (default: {}) | | pathComponents | object | Yes | Components to render for different path types | | completedPathComponents | object | Yes | Components to render for completed path types | | completedLevelComponent | element | Yes | Component to render for completed levels | | futureLevelComponent | element | Yes | Component to render for future levels | | onSave | function | No | Callback function when positions are saved | | cellWidth | number | No | Width of each matrix cell in pixels (default: 80) | | cellHeight | number | No | Height of each matrix cell in pixels (default: 80) | | cellGap | number | No | Gap between cells in pixels (default: 0) |

Position Object Structure

The position object uses keys as unique identifiers and contains the following properties:

For levels:

{
  x: number, // x position in the matrix
  y: number, // y position in the matrix
  type: "level", // type of the node
  status: "completed" | "future", // status of the level
  levelContent: string, // content to display in the level
  order: number // order/sequence number of the level
}

For paths:

{
  x: number, // x position in the matrix
  y: number, // y position in the matrix
  type: "path", // type of the node
  status: "completed" | "future", // status of the path
  pathComponent: "horizontal" | "vertical" | "diagonalRightDown" | "diagonalLeftDown" // type of path
}

Dynamic Status Changes

You can dynamically update the status of levels and paths based on user progress or other conditions. This allows creating interactive roadmaps that visually update as users progress.

Example with Current Level Tracking

function App() {
  // Track the current level (could be from user progress, API data, etc.)
  const [currentLevel, setCurrentLevel] = useState(1);

  // Define positions with dynamic status based on currentLevel
  const positions = {
    "level-1": {
      x: 1,
      y: 0,
      type: "level",
      status: currentLevel >= 1 ? "completed" : "future", // Conditional status
      levelContent: "1",
      order: 1,
    },
    "path-1-2": {
      x: 1,
      y: 1,
      type: "path",
      status: currentLevel >= 2 ? "completed" : "future", // Conditional status
      pathComponent: "vertical",
    },
    "level-2": {
      x: 1,
      y: 2,
      type: "level",
      status: currentLevel >= 2 ? "completed" : "future", // Conditional status
      levelContent: "2",
      order: 2,
    },
    // More positions...
  };

  // Level click handler that updates progress
  const handleLevelClick = (order) => {
    setCurrentLevel(order);
  };

  return (
    <RoadmapViewer
      positions={positions}
      onLevelClick={handleLevelClick}
      // Other props...
    />
  );
}

With this approach, whenever currentLevel changes, the roadmap will automatically update with completed and future sections visually distinguished.

License

MIT © [Your Name]

Component Props

Path Components

When creating custom path components, the component will receive the following props:

• key: A unique identifier for the path
• orientation: The orientation of the path ('horizontal', 'vertical', 'diagonal-right-down', etc.)

Example path component:

const PathComponent = ({ orientation }) => {
  // Render different path styles based on orientation
  let pathStyles = {};

  switch (orientation) {
    case "vertical":
      pathStyles = { width: "8px", height: "100%" };
      break;
    case "horizontal":
    default:
      pathStyles = { width: "100%", height: "8px" };
  }

  return <div style={pathStyles} />;
};

// Then use it in RoadmapViewer
<RoadmapViewer
  // ...other props
  pathComponent={<PathComponent />}
/>;

Level Components

Level components will receive:

• key: A unique identifier for the level