mpComponents

A modern, accessible React component library built with Radix UI primitives, TanStack Form & Tables, and plain CSS.

📖 Documentation • 🚀 Quick Start • 🤝 Contributing • 📋 Guidelines

📚 Documentation

• 📖 View Live Documentation & Examples →
• 🤝 Contributing Guide - Get started with development
• ⚡ Quick Reference - One-page cheat sheet for component development
• 📋 Full Guidelines - Complete development standards
• 🧪 Testing Guide - Component testing documentation

✨ Features

• 🔷 Type-Safe Components — Built with TypeScript in strict mode
• ♿ Accessibility First — WCAG 2.1 AA compliant with Radix UI primitives
• 📊 TanStack Integration — Advanced form and table handling with TanStack Form & Tables
• 🎨 CSS-Based Styling — Plain CSS with BEM naming convention, no CSS-in-JS
• 📦 Tree-Shakeable — Clean barrel exports for optimal bundle size
• 🧪 Well Tested — Comprehensive unit and component tests with Playwright & Vitest
• 🎯 Developer Experience — Hot reload, TypeScript autocomplete, and extensive documentation

🚀 Installation

# npm
npm install @konradullrich/mp-components

# pnpm
pnpm add @konradullrich/mp-components

# yarn
yarn add @konradullrich/mp-components

Note: This library requires React 19+ as a peer dependency.

📖 Usage

Import components and styles in your React application:

import { Button, Input, Dialog } from "@konradullrich/mp-components";
import "@konradullrich/mp-components/styles";

export function App() {
  return (
    <div>
      <Button variant="primary">Click me</Button>
      <Input placeholder="Enter text..." />
      <Dialog>
        <Dialog.Trigger asChild>
          <Button>Open Dialog</Button>
        </Dialog.Trigger>
        <Dialog.Content>
          <Dialog.Title>Welcome</Dialog.Title>
          <Dialog.Description>
            This is a dialog component from mpComponents.
          </Dialog.Description>
        </Dialog.Content>
      </Dialog>
    </div>
  );
}

For more examples and interactive demos, visit the Live Documentation.

📦 Component Categories

Components are organized into logical categories for easy discovery and usage:

common/

General-purpose components

• Button - Primary action element
• Badge - Status indicators
• Icon - Icon wrapper
• Tooltip - Contextual help
• Dialog - Modal dialogs
• Dropdown - Menu dropdowns

controls/

Form elements & inputs

• Input - Text input fields
• Select - Dropdown selectors
• Checkbox - Toggle checkboxes
• Radio - Radio buttons
• Toggle - On/off switches

data-display/

Data presentation

• Table - Data tables
• List - Item lists
• Card - Content cards
• Tree - Hierarchical data

layout/

Page structure

• Sidebar - Side navigation
• Header - Page headers
• Footer - Page footers
• Navigation - Nav menus

styles/

Global CSS variables, themes, and utility styles for consistent design.

🛠️ Development

Prerequisites

• Node.js 18+ or 20+
• pnpm 8+ (recommended) or npm

Setup

Clone the repository and install dependencies:

git clone https://github.com/konradUllrich/componentLibary.git
cd componentLibary
pnpm install

Available Scripts

| Command | Description | | ------------------ | -------------------------------------- | | pnpm build | Build the library for production | | pnpm build:watch | Build in watch mode for development | | pnpm demo | Run the interactive demo site locally | | pnpm demo:build | Build the demo site for deployment | | pnpm lint | Lint all TypeScript and TSX files | | pnpm type-check | Run TypeScript compiler checks | | pnpm test | Run unit tests with Vitest | | pnpm test:ui | Run unit tests with Vitest UI | | pnpm test:ct | Run component tests with Playwright | | pnpm test:ct:ui | Run component tests with Playwright UI | | pnpm test:e2e | Run end-to-end tests |

Demo Site

The demo site showcases all components with interactive examples and comprehensive documentation.

Run locally:

pnpm demo

Build for production:

pnpm demo:build

Router Configuration

The demo site uses TanStack Router with configurable routing modes:

• URL Mode (default): Traditional routing with clean URLs (e.g., /components/button)
• Param Mode: Routes stored in URL parameters (e.g., /?route=/components/button)

To use param mode:

VITE_ROUTER_MODE=param pnpm demo

For more details, see demo/ROUTER_CONFIG.md.

📂 Project Structure

mpComponents/
├── common/              # Shared, reusable components (Button, Badge, Icon, etc.)
├── controls/            # Form controls and input components (Input, Select, Checkbox, etc.)
├── data-display/        # Data presentation components (Table, List, Card, etc.)
├── layout/              # Layout components (Sidebar, Header, Footer, etc.)
├── styles/              # Global styles, CSS variables, and theming
├── demo/                # Interactive demo site with all component examples
├── e2e/                 # End-to-end tests
├── docs/                # Generated documentation
├── index.ts             # Main barrel export file
├── package.json         # Package configuration
└── README.md            # This file

🧪 Testing

This library maintains high code quality through comprehensive testing:

• Component Tests - Playwright component testing with visual and interaction validation
• Unit Tests - Vitest for logic and utility testing
• Accessibility Tests - Automated a11y checks using axe-core
• E2E Tests - Full application flow testing with Playwright

All tests run automatically in CI/CD pipeline on every commit.

Learn more: TESTING.md

🎨 Component Development Guidelines

This library follows strict guidelines to ensure quality, accessibility, and maintainability:

| Guideline | Requirement | | ----------------- | ------------------------------------------------------------------ | | TypeScript | Strict mode enabled - Zero type errors, no any or unknown | | Styling | Plain CSS with BEM naming convention - No CSS modules or CSS-in-JS | | Accessibility | WCAG 2.1 AA compliance required - Full keyboard navigation | | File Size | Components ≤ 100 lines - Split into smaller files if needed | | Radix UI | Use Radix primitives for complex interactive components | | Testing | Playwright component tests with a11y checks required | | Documentation | JSDoc comments and interactive examples required |

📚 Documentation Resources

• CONTRIBUTING.md - Start here for development setup and workflow
• QUICK_REFERENCE.md - One-page cheat sheet for quick reference
• mpComponents.instructions.md - Complete development standards and guidelines

🤝 Contributing

We welcome contributions! Please read our Contributing Guide before submitting any pull requests.

Before contributing:

1. ✅ Read the Contributing Guide and Component Guidelines
2. ✅ Ensure all code passes TypeScript checks (pnpm type-check)
3. ✅ Follow BEM naming convention for CSS classes
4. ✅ Meet WCAG 2.1 AA accessibility standards
5. ✅ Write component tests with accessibility checks
6. ✅ Keep component files ≤ 100 lines (split if larger)

Quick Links

• Component Development Guide
• Quick Reference Cheat Sheet
• Complete Guidelines
• Testing Documentation

📄 License

MIT License - see LICENSE for details.

Copyright (c) 2025 Intrexx

💬 Support & Community

• 📖 Documentation: https://konradullrich.github.io/componentLibary/
• 🐛 Issues: GitHub Issues
• 💡 Discussions: GitHub Discussions
• 📦 npm Package: @konradullrich/mp-components

Built with ❤️ using React • Radix UI • TanStack