npm package: @macolmenerori/component-library
Description: A modern React component library built with TypeScript, providing reusable UI components for your React applications.
Author: macolmenerori
Latest version: 1.4.0

# @macolmenerori/component-library

A modern React component library built with TypeScript, providing reusable UI components for your React applications.

## Features

- Built with React 18/19 and TypeScript
- Fully typed components with TypeScript declarations
- ESM and CommonJS support
- **Subpath exports** for tree-shaking and optional dependencies
- Strict TypeScript configuration for type safety

## Installation

This package is published to [npm](https://www.npmjs.com/package/@macolmenerori/component-library) and can be installed directly without any additional configuration.

Using npm:

```bash
npm install @macolmenerori/component-library
```

Using pnpm:

```bash
pnpm add @macolmenerori/component-library
```

Using yarn:

```bash
yarn add @macolmenerori/component-library
```

## Usage

Import components from the library. You can use the main entry point or subpath imports for better tree-shaking.

### Subpath Exports

| Import Path                                         | Components      | Dependencies Required             |
| --------------------------------------------------- | --------------- | --------------------------------- |
| `@macolmenerori/component-library`                  | All             | react, react-markdown, remark-gfm |
| `@macolmenerori/component-library/theme-switch`     | ThemeSwitch     | react                             |
| `@macolmenerori/component-library/monthly-calendar` | MonthlyCalendar | react                             |
| `@macolmenerori/component-library/markdown-render`  | MarkdownRender  | react, react-markdown, remark-gfm |

### Available Components

<details>
<summary><strong>ThemeSwitch</strong> - An animated toggle switch for light/dark theme switching</summary>

A visually appealing theme toggle component with sun/moon animations, clouds, and stars.

**Props:**

- `enableDarkMode` (boolean, required): Current dark mode state
- `setEnableDarkMode` (function, required): Callback to update dark mode state
- `size` (optional): Size variant - `'small'`, `'medium'`, or `'large'` (default: `'large'`)

**Example:**

```tsx
import { useState } from 'react';
// Import CSS separately (required for styling)
import '@macolmenerori/component-library/theme-switch-css';
// Subpath import (recommended - no react-markdown dependency required)
import { ThemeSwitch } from '@macolmenerori/component-library/theme-switch';

function App() {
  const [darkMode, setDarkMode] = useState(false);

  return (
    <div>
      <ThemeSwitch enableDarkMode={darkMode} setEnableDarkMode={setDarkMode} size="medium" />
    </div>
  );
}
```

> **Note:** ThemeSwitch requires manual CSS import to support SSG/SSR environments. Import the CSS file before using the component.

</details>

<details>
<summary><strong>MonthlyCalendar</strong> - A monthly calendar grid with annotation support</summary>

A zero-dependency monthly calendar component rendered as a semantic HTML table. Supports per-day annotations (any ReactNode), customizable headers, inline style overrides, and built-in light/dark themes.

**Props:**

- `year` (number, required): Full four-digit year (e.g. 2026)
- `month` (number, required): Month to display, 1-based (1 = January, 12 = December)
- `annotations` ((ReactNode | null | undefined)[], optional): Array of content per day. `annotations[0]` maps to Day 1
- `headers` (string[7], optional): Array of 7 weekday labels. Omit to hide the header row
- `style` (CSSProperties, optional): Inline styles merged onto the `<table>` element
- `darkMode` (boolean, optional): Enables dark color theme (default: `false`)

**Example:**

```tsx
import { MonthlyCalendar } from '@macolmenerori/component-library/monthly-calendar';

function App() {
  return (
    <MonthlyCalendar
      year={2026}
      month={2}
      headers={['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']}
    />
  );
}
```

> **Note:** No CSS import is needed. MonthlyCalendar uses inline styles only.

</details>

<details>
<summary><strong>MarkdownRender</strong> - A component for rendering markdown strings as HTML</summary>

A simple and flexible markdown renderer with GitHub Flavored Markdown (GFM) support, including tables, task lists, strikethrough, and code blocks.

> **Note:** This component requires `react-markdown` and `remark-gfm` peer dependencies.

**Props:**

- `content` (string, required): The markdown string to render
- `className` (string, optional): CSS class name for the container element

**Features:**

- Full GitHub Flavored Markdown support
- Tables, task lists, strikethrough
- Code blocks with syntax highlighting support
- Autolinks
- Customizable styling via className prop

**Example:**

```tsx
import { MarkdownRender } from '@macolmenerori/component-library/markdown-render';

function App() {
  const markdownContent = `
# Hello World

This is **bold** and this is *italic*.

## Features
- Lists
- ~~Strikethrough~~
- [Links](https://example.com)
- \`inline code\`

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
  `;

  return (
    <div>
      <MarkdownRender content={markdownContent} className="my-markdown" />
    </div>
  );
}
```

</details>

## Peer Dependencies

**Required:**

- `react`: ^18.0.0 or ^19.0.0
- `react-dom`: ^18.0.0 or ^19.0.0

**Optional** (only needed for MarkdownRender):

- `react-markdown`: ^10.0.0
- `react-gfm`: ^4.0.0

If you only use ThemeSwitch via the subpath import (`/theme-switch`), you don't need to install react-markdown.

## Development

This section is for contributors working on the library itself.

### Prerequisites

- Node.js 24
- pnpm 10.28.0

### Setup

```bash
pnpm install
```

### Available Scripts

- `pnpm dev` - Start the development server on port 3000
- `pnpm build` - Build the library for distribution
- `pnpm preview` - Preview the production build
- `pnpm prettify` - Format code with Prettier
- `pnpm lint` - Lint code with ESLint
- `pnpm types` - Type check with TypeScript

### Building

To build the library:

```bash
pnpm build
```

This will generate multiple entry points:

- `dist/index.js` / `dist/index.cjs` - Main entry (all components)
- `dist/theme-switch.js` / `dist/theme-switch.cjs` - ThemeSwitch only
- `dist/monthly-calendar.js` / `dist/monthly-calendar.cjs` - MonthlyCalendar only
- `dist/markdown-render.js` / `dist/markdown-render.cjs` - MarkdownRender only
- `dist/types/` - TypeScript declarations

### Publishing

To publish a new version:

1. Bump version with `pnpm release <major | minor | patch>`
2. Build the library: `pnpm build`
3. Publish: `pnpm publish`

## Technology Stack

- **React** 18.0.0 || 19.0.0 - UI library
- **TypeScript** - Type safety
- **Vite** - Build tool and dev server
- **ESLint** - Code linting
- **Prettier** - Code formatting

## License

MIT

## Repository

[https://github.com/macolmenerori/component-library](https://github.com/macolmenerori/component-library)