@kalxjs/ui

@kalxjs/ui

Modern, accessible UI component library for KALXJS applications.

Features

✨ 10+ Ready-to-Use Components - Button, Input, Modal, Card, Alert, Badge, Tooltip, Dropdown, Tabs, and more

🎨 Complete Design System - Colors, typography, spacing, and shadows with light/dark mode

♿ Accessible by Default - WCAG 2.1 Level AA compliant, keyboard navigation, ARIA attributes

🌙 Dark Mode Support - Built-in theme system with easy mode switching

📱 Responsive - Mobile-first design with breakpoint utilities

🎯 TypeScript Ready - Full type definitions (coming soon)

⚡ Tree-Shakeable - Import only what you need

🎭 Customizable - Override styles and extend components easily

Installation

npm install @kalxjs/ui @kalxjs/core @kalxjs/a11y

Quick Start

1. Install the plugin

import { createApp } from '@kalxjs/core';
import KalxjsUI from '@kalxjs/ui';
import '@kalxjs/ui/styles.css'; // Optional: if using pre-compiled CSS

const app = createApp(App);

// Install with default theme
app.use(KalxjsUI);

// Or install with custom theme
app.use(KalxjsUI, {
    theme: {
        mode: 'dark',
        colors: {
            primary: {
                500: '#your-color',
            },
        },
    },
});

app.mount('#app');

2. Use components

import { Button, Input, Modal, Card } from '@kalxjs/ui';

export default {
    template: `
        <div>
            <Button variant="primary" @click="handleClick">
                Click Me
            </Button>

            <Input
                v-model="email"
                type="email"
                label="Email"
                placeholder="Enter your email"
            />

            <Modal v-model="showModal" title="Hello World">
                <p>This is a modal</p>
            </Modal>

            <Card>
                <template #header>
                    <h3>Card Title</h3>
                </template>
                <p>Card content goes here</p>
            </Card>
        </div>
    `,
};

Components

Button

Versatile button component with multiple variants and sizes.

<Button variant="primary" size="lg" @click="handleClick">
    Primary Button
</Button>

<Button variant="outline" loading>
    Loading...
</Button>

<Button variant="danger" disabled>
    Disabled
</Button>

Props:

• variant: 'primary' | 'secondary' | 'success' | 'danger' | 'outline' | 'ghost' | 'link'
• size: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
• disabled: boolean
• loading: boolean
• fullWidth: boolean

Input

Form input with validation and helper text.

<Input
    v-model="username"
    label="Username"
    placeholder="Enter username"
    hint="Choose a unique username"
    error="Username is required"
    required
    clearable
/>

Props:

• type: 'text' | 'password' | 'email' | 'number' | ...
• label: string
• placeholder: string
• error: string
• hint: string
• disabled: boolean
• clearable: boolean
• showPasswordToggle: boolean (for password inputs)

Modal

Accessible modal dialog with focus trap.

<Modal
    v-model="isOpen"
    title="Confirm Action"
    size="md"
    @close="handleClose"
>
    <p>Are you sure you want to continue?</p>
    <template #footer>
        <Button @click="isOpen = false">Cancel</Button>
        <Button variant="primary" @click="confirm">Confirm</Button>
    </template>
</Modal>

Props:

• modelValue: boolean
• title: string
• size: 'sm' | 'md' | 'lg' | 'xl'
• closeOnOverlay: boolean
• closeOnEsc: boolean

Card

Container component with elevation.

<Card variant="elevated" hoverable>
    <template #header>
        <h3>Card Title</h3>
    </template>
    <p>Card content</p>
    <template #footer>
        <Button>Action</Button>
    </template>
</Card>

Alert

Feedback messages for users.

<Alert variant="success" title="Success!" closable>
    Your changes have been saved.
</Alert>

<Alert variant="danger">
    An error occurred. Please try again.
</Alert>

Theme System

Using the theme

import { useTheme } from '@kalxjs/ui';

export default {
    setup() {
        const { theme, toggleMode, isDark } = useTheme();

        return {
            theme,
            toggleMode,
            isDark,
        };
    },
};

Custom theme

import { createTheme, applyTheme } from '@kalxjs/ui';

const customTheme = createTheme({
    mode: 'dark',
    colors: {
        primary: '#your-color',
    },
});

applyTheme(customTheme);

Composables

useMediaQuery

import { useMediaQuery, useIsMobile, usePrefersDark } from '@kalxjs/ui';

const isMobile = useIsMobile();
const prefersDark = usePrefersDark();
const isLarge = useMediaQuery('(min-width: 1200px)');

Accessibility

All components are built with accessibility in mind:

• ✅ Keyboard navigation
• ✅ Screen reader support
• ✅ ARIA attributes
• ✅ Focus management
• ✅ Color contrast (WCAG AA)

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

License

MIT

Contributing

Contributions are welcome! Please read our contributing guide.