@damarkuncoro/ui-components

A comprehensive collection of React UI components built with TypeScript, following atomic design principles.

📦 Installation

npm install @damarkuncoro/ui-components @damarkuncoro/ui-core

💅 Styling Configuration (Tailwind CSS)

This library uses Tailwind CSS for styling. To ensure styles are correctly applied, you must add the package paths to your project's tailwind.config.js content array.

// tailwind.config.js
module.exports = {
  content: [
    // ... your other paths
    "./node_modules/@damarkuncoro/ui-components/dist/**/*.{js,jsx,ts,tsx}"
  ],
  // ... rest of your config
}

🎨 Component Categories

Atoms (Basic Elements)

Fundamental UI elements that can't be broken down further.

import { Button, Input, Switch, Avatar } from '@damarkuncoro/ui-components/atoms';

// Basic usage
<Button variant="primary" size="md" onClick={handleClick}>
  Click me
</Button>

<Input
  placeholder="Enter text"
  value={value}
  onChange={setValue}
/>

<Switch
  checked={isEnabled}
  onChange={setIsEnabled}
  label="Enable feature"
/>

Molecules (Composite Elements)

Groups of atoms that form more complex UI patterns.

import { Card, Form, Pagination, StatsCard } from '@damarkuncoro/ui-components/molecules';

// Card component
<Card title="User Profile" className="max-w-md">
  <Avatar src={user.avatar} name={user.name} />
  <div className="mt-4">
    <h3 className="font-semibold">{user.name}</h3>
    <p className="text-gray-600">{user.email}</p>
  </div>
</Card>

// Form with validation
<Form onSubmit={handleSubmit}>
  <Input name="email" type="email" required />
  <Input name="password" type="password" required />
  <Button type="submit">Login</Button>
</Form>

// Pagination
<Pagination
  currentPage={currentPage}
  totalPages={totalPages}
  onPageChange={setCurrentPage}
/>

Organisms (Complex Components)

Large, complex components that contain molecules and atoms.

import { Table, Modal, DashboardLayout } from '@damarkuncoro/ui-components/organisms';

// Data table
<Table
  columns={columns}
  data={tableData}
  sortable
  pagination
/>

// Modal dialog
<Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
  <Modal.Header>Confirm Action</Modal.Header>
  <Modal.Body>Are you sure you want to proceed?</Modal.Body>
  <Modal.Footer>
    <Button variant="secondary" onClick={() => setIsOpen(false)}>
      Cancel
    </Button>
    <Button variant="primary" onClick={handleConfirm}>
      Confirm
    </Button>
  </Modal.Footer>
</Modal>

// Dashboard layout
<DashboardLayout
  sidebar={<Sidebar />}
  header={<Header />}
>
  <MainContent />
</DashboardLayout>

🎨 Theming & Styling

Components are designed to work with the theme system:

import { ThemeProvider } from '@damarkuncoro/ui-themes';
import '@damarkuncoro/ui-themes/skins/metronic';

function App() {
  return (
    <ThemeProvider theme="metronic">
      <Button variant="primary">Themed Button</Button>
    </ThemeProvider>
  );
}

📋 Component API

Shared Props

All components support these common props:

interface BaseComponentProps {
  className?: string;        // Custom CSS classes
  style?: React.CSSProperties; // Inline styles
  'data-testid'?: string;    // Test ID for testing
  id?: string;              // HTML ID attribute
}

Size Variants

type ComponentSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

Color Variants

type ComponentVariant =
  | 'primary'
  | 'secondary'
  | 'success'
  | 'danger'
  | 'warning'
  | 'info'
  | 'light'
  | 'dark';

🔧 Advanced Usage

Custom Styling

// Using className prop
<Button
  className="custom-button"
  variant="primary"
>
  Custom Styled Button
</Button>

// Using style prop
<Input
  style={{ borderRadius: '8px', borderColor: '#custom' }}
  placeholder="Custom styled input"
/>

Composition

// Building complex UIs by composition
function UserCard({ user }) {
  return (
    <Card className="user-card">
      <div className="flex items-center space-x-4">
        <Avatar src={user.avatar} name={user.name} />
        <div className="flex-1">
          <h3 className="font-semibold">{user.name}</h3>
          <p className="text-gray-600">{user.email}</p>
        </div>
        <Button variant="secondary" size="sm">
          Edit
        </Button>
      </div>
    </Card>
  );
}

Form Integration

import { Form, Input, Select, Checkbox } from '@damarkuncoro/ui-components';

function ContactForm() {
  const handleSubmit = (data) => {
    console.log('Form data:', data);
  };

  return (
    <Form onSubmit={handleSubmit} className="max-w-md">
      <Input
        name="name"
        label="Full Name"
        required
        placeholder="Enter your name"
      />

      <Input
        name="email"
        type="email"
        label="Email"
        required
        placeholder="Enter your email"
      />

      <Select
        name="country"
        label="Country"
        options={[
          { value: 'us', label: 'United States' },
          { value: 'ca', label: 'Canada' },
          { value: 'uk', label: 'United Kingdom' }
        ]}
      />

      <Checkbox
        name="newsletter"
        label="Subscribe to newsletter"
      />

      <Button type="submit" variant="primary" className="w-full">
        Submit
      </Button>
    </Form>
  );
}

♿ Accessibility

All components are built with accessibility in mind:

• Keyboard Navigation: Full keyboard support
• Screen Readers: Proper ARIA attributes
• Focus Management: Visible focus indicators
• Semantic HTML: Correct element usage

// Accessible button with loading state
<Button
  loading={isSubmitting}
  disabled={isSubmitting}
  aria-describedby="submit-help"
>
  {isSubmitting ? 'Submitting...' : 'Submit Form'}
</Button>
<span id="submit-help" className="sr-only">
  This will send your information to our servers
</span>

🧪 Testing

Components include data attributes for easy testing:

// Component with test ID
<Button data-testid="submit-button">
  Submit
</Button>

// Testing with React Testing Library
const button = screen.getByTestId('submit-button');
fireEvent.click(button);

📚 Component List

Atoms (16 components)

• Avatar - User avatar display
• Badge - Status indicators
• Button - Interactive buttons
• Checkbox - Boolean input
• Divider - Content separators
• Icon - Icon display
• Input - Text input
• ProgressBar - Progress indicators
• Radio - Single selection
• Select - Dropdown selection
• Skeleton - Loading placeholders
• Spinner - Loading indicators
• Switch - Toggle input
• Text - Text display
• Textarea - Multi-line text input
• Tooltip - Contextual help

Molecules (14 components)

• Accordion - Collapsible content
• Alert - Status messages
• Breadcrumb - Navigation path
• Card - Content containers
• Chart - Data visualization
• EmptyState - Empty state display
• Grid - Layout grids
• Pagination - Page navigation
• Stack - Vertical layouts
• StatsCard - Statistics display
• StatWidget - Metric widgets
• Timeline - Event timelines
• Toast - Notification messages
• UserCard - User information

Organisms (7 components)

• Drawer - Slide-out panels
• Form - Complex forms
• Modal - Dialog overlays
• PageHeader - Page headers
• Table - Data tables
• Tabs - Tabbed interfaces

🔄 Migration Guide

From v0.x to v1.0

Breaking Changes

• Component APIs standardized
• Hook signatures updated
• Theme integration required

Migration Steps

// Before (v0.x)
import { Button } from '@damarkuncoro/ui-components';
<Button primary large>Click me</Button>

// After (v1.0)
import { Button } from '@damarkuncoro/ui-components';
<Button variant="primary" size="lg">Click me</Button>

📄 License

MIT License - see LICENSE file for details.