npm package: @jaimejesusserrano/roadmap-milestones
Description: The Roadmap Milestones component is a board with a lot of features, functionalities or whatever where a user can see all of them divided by categories and milestones
Author: Jaime Jesús Serrano
Latest version: 1.1.0

# Roadmap Milestones

## Installation

This project uses [pnpm](https://pnpm.io/) as the package manager.
Please install the dependencies with:

```sh
pnpm install
```

## How use it

Add and use this component in your project. Example of use:

- [React Repository example](https://github.com/JaimeJesusSerrano/react-roadmap-milestones-example)
- [Next Web example](https://react-roadmap-milestones-example.vercel.app/roadmap)

## Description

The Roadmap Milestones component is a board with a lot of features, functionalities or whatever where a user can see all of them divided by categories and milestones.

Several examples than can help us to understand it:

- **Cookbook**: maybe you what add recipes of different categories and you what show it by milestones as timeline or book version.
- **Video game**: where we can see the different features (deployed, in development or to be develop) in several milestones as a timeline.
- **Software project** like this component. Yes, use this component to explain the evolution of himself.
- Definitely **The evolution of any project or idea to be showed by milestones**.

## Usage

  ### Basic example

  First, install the package:

  ```sh
  npm install @jaimejesusserrano/roadmap-milestones
  ```

  Here is how you can use the component in different frameworks, as it is a native Web Component.

  #### React 19+ (Native Support)

  React 19 natively supports Web Components and can pass complex objects seamlessly.

  ```tsx
  import { useState } from 'react';
  import type { IRoadmapMilestones } from '@jaimejesusserrano/roadmap-milestones';
  import '@jaimejesusserrano/roadmap-milestones'; // Import to register the component

  export default function App() {
    const [data] = useState<IRoadmapMilestones>({
      name: 'Example',
      milestones: [
        {
          name: '0.1',
          status: 'pending',
          goals: [
            {
              name: 'Goal 1',
              description: 'Goal description',
              shortDescription: 'Short goal description',
              status: 'pending',
              updateDate: new Date(),
            }
          ],
        }
      ],
    });

    return (
      <div style={{ height: 600, width: 1000 }}>
        {/* Use the Custom Element tag and pass objects directly */}
        <rm-roadmap-milestones roadmapMilestonesData={data}>
        </rm-roadmap-milestones>
      </div>
    );
  }
  ```

  #### React 18 and below

  React 18 and older versions cannot pass objects directly to Web Components attributes. You need to use the official `@lit/react` wrapper to use it as a standard React component.

  ```tsx
  import React, { useState } from 'react';
  import { createComponent } from '@lit/react';
  import { RoadmapMilestones, type IRoadmapMilestones } from '@jaimejesusserrano/roadmap-milestones';
  
  // Create a React wrapper for the Web Component
  export const RoadmapMilestonesReact = createComponent({
    tagName: 'rm-roadmap-milestones',
    elementClass: RoadmapMilestones,
    react: React,
  });

  export default function App() {
    const [data] = useState<IRoadmapMilestones>({ /* ... your data ... */ });

    return (
      <div style={{ height: 600, width: 1000 }}>
        {/* Now you can use it just like a normal React Component */}
        <RoadmapMilestonesReact roadmapMilestonesData={data} />
      </div>
    );
  }
  ```

  #### Angular

  Angular has excellent built-in support for Web Components. Remember to add `CUSTOM_ELEMENTS_SCHEMA` to your module or standalone component.

  ```typescript
  import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
  import type { IRoadmapMilestones } from '@jaimejesusserrano/roadmap-milestones';
  import '@jaimejesusserrano/roadmap-milestones'; // Import to register the component

  @Component({
    selector: 'app-root',
    standalone: true,
    schemas: [CUSTOM_ELEMENTS_SCHEMA], // <-- Required for custom tags
    template: `
      <div style="height: 600px; width: 1000px;">
        <rm-roadmap-milestones [roadmapMilestonesData]="data"></rm-roadmap-milestones>
      </div>
    `
  })
  export class AppComponent {
    data: IRoadmapMilestones = { /* ... your data ... */ };
  }
  ```

  #### Vue 3

  Vue also supports Custom Elements natively. You should use `.prop` modifier to explicitly pass complex data as properties.

  ```vue
  <script setup lang="ts">
  import { ref } from 'vue';
  import type { IRoadmapMilestones } from '@jaimejesusserrano/roadmap-milestones';
  import '@jaimejesusserrano/roadmap-milestones'; // Import to register the component

  const data = ref<IRoadmapMilestones>({ /* ... your data ... */ });
  </script>

  <template>
    <div style="height: 600px; width: 1000px;">
      <!-- Use the .prop modifier to pass objects/arrays correctly -->
      <rm-roadmap-milestones .roadmapMilestonesData="data"></rm-roadmap-milestones>
    </div>
  </template>
  ```

### Override CSS

Roadmap Milestones provides its own CSS styles but you can override them. You can modify the theme that include the color palette, breakpoints and devices or you can modify the entire CSS styles, as you prefer.

```javascript
  import { RoadmapMilestones, type IRoadmapMilestones, type ITheme } from '@jaimejesusserrano/roadmap-milestones'

  const roadmapMilestonesData: IRoadmapMilestones = {
    milestones: [
      {
        name: '0.1',
        status: 'pending',
        goals: [
          {
            name: 'Goal 1',
            description: 'Goal description',
            shortDescription: 'Short goal description',
            status: 'pending',
            updateDate: new Date(),
          }
        ],
      }
    ],
    name: 'Example',
  }

  const className = 'my-custom-className'
  const theme: ITheme = {}

  return (
    <div style={{height: 600, width: 1000}}>
      <RoadmapMilestones
        className={className}
        roadmapMilestonesData={roadmapMilestonesData}
        theme={theme}
      />
    </div>
  )
```

## Future ideas to be developed (suggestions are accepted)

- ~~Overwrite styles, to allow config your own CSS.~~ (Done)

## Available Scripts

In the project directory, you can run:

### `npm run build`

Builds the component.

## To update the package in NPM

npm publish