@mrintel/villain-ui

A luxury Svelte 5 component library featuring a Modern Villain Luxury aesthetic. Built on Onyx Black backgrounds with Royal Purple accents, glass morphism, and neon edges for modern web applications that demand commanding elegance and exceptional user experience.

✨ Features

• 🚀 Svelte 5 with Runes - Built on the latest Svelte 5 reactivity system with full TypeScript support
• 🎨 Modern Villain Luxury - Onyx Black base with Royal Purple accents, glass morphism, and commanding neon edges
• 🎭 Tailwind CSS v4 - Powered by the latest Tailwind with CSS variable theming
• 🌳 Tree-Shakeable - Import only what you need for optimal bundle size
• 🎯 Fully Typed - Strict TypeScript mode with complete type definitions
• 🎬 Premium Motion - Smooth animations with custom luxury easing curves
• 🔧 Highly Customizable - Theme via CSS variables without touching component code
• ♿ Accessible - ARIA-compliant components following WAI-ARIA best practices

📦 Installation

# npm
npm install @mrintel/villain-ui

# pnpm
pnpm add @mrintel/villain-ui

# yarn
yarn add @mrintel/villain-ui

Note on Imports: All components are exported from the root package (@mrintel/villain-ui). Category-specific subpath imports (e.g., @mrintel/villain-ui/buttons) are not provided, as the library is designed for tree-shaking at the component level. Your bundler will automatically include only the components you import.

Peer Dependencies

Install the required peer dependency:

npm install svelte@^5.0.0

Note on Tailwind CSS: The library uses Tailwind CSS v4 internally for styling, but it is not required as a peer dependency. The compiled theme CSS is included in the package. You only need to install Tailwind CSS in your project if you want to extend the library's theme with custom Tailwind utilities or use Tailwind for your own application styling.

Import Theme

Important: The theme CSS is not automatically imported when you use components. You must explicitly import it in your app's entry point to apply the default styles.

Import the theme CSS in your app's entry point (e.g., +layout.svelte in SvelteKit or main.ts in Vite):

import '@mrintel/villain-ui/theme.css';

This explicit import strategy gives you full control over styling and allows you to:

• Use a custom theme instead of the default
• Conditionally load themes
• Override theme variables before or after the default theme loads

🚀 Quick Start

SvelteKit Setup

<!-- src/routes/+layout.svelte -->
<script>
  import '@mrintel/villain-ui/theme.css';
</script>

<slot />

Basic Usage

<script>
  import { Button, Card } from '@mrintel/villain-ui';
</script>

<Card padding="lg">
  <h1>Welcome to @mrintel/villain-ui</h1>
  <p>Build luxury interfaces with ease.</p>
  <Button variant="primary">Get Started</Button>
</Card>

✨ Key Features

Icon Support with Snippets

Comprehensive icon snippet support across the entire component library for maximum flexibility:

Forms:

• Input, Textarea, Select: iconBefore and iconAfter snippets for flexible positioning
• Checkbox, Switch: iconBefore snippet for visual enhancement
• RadioGroup: Per-option iconBefore in options array for rich radio lists
• FileUpload: Custom icon snippet to override default upload icon

Buttons & Navigation:

• Button, LinkButton: iconBefore and iconAfter snippets for flexible positioning
• Breadcrumbs: Per-item icon in items array for visual breadcrumb trails
• Pagination: prevIcon and nextIcon snippets for custom navigation arrows
• Tabs: iconBefore in tab objects for tabbed navigation

Data Display:

• Badge: Simple icon snippet for status indicators (not iconBefore, as it's a simple badge)
• Tag: Simple icon snippet for tags
• List: Per-item icon in items array for icon lists
• Avatar: Image/initials support (not snippet-based)

Overlays:

• Alert: iconBefore snippet for custom alert icons
• Modal, Toast, Drawer: iconBefore snippet for title icons

Navigation:

• Menu: Per-item icon in items array
• DropdownMenu, ContextMenu: Per-item icon in items array with structured MenuItem[] interface

Icon API Patterns

The library uses three consistent icon patterns:

1. Simple icon snippet - Single icon?: Snippet for components with one icon position:

<Tag>
  {#snippet icon()}
    <StarIcon class="w-4 h-4" />
  {/snippet}
  Featured
</Tag>

2. Positional icon snippets - Separate iconBefore/iconAfter snippets for flexible positioning:

<Button>
  {#snippet iconAfter()}
    <ArrowRightIcon class="w-5 h-5" />
  {/snippet}
  Next
</Button>

<!-- Or with both icons -->
<LinkButton>
  {#snippet iconBefore()}
    <HomeIcon class="w-5 h-5" />
  {/snippet}
  Home
  {#snippet iconAfter()}
    <ExternalLinkIcon class="w-4 h-4" />
  {/snippet}
</LinkButton>

3. Per-item icons - Icons specified in item/option arrays:

<script>
  const options = [
    { 
      value: 'option1', 
      label: 'Option 1',
      iconBefore: IconSnippet // Snippet reference
    }
  ];
</script>

<RadioGroup {options} bind:value={selected} />
<Breadcrumbs items={breadcrumbItems} />

Best Practices

• Consistent sizing: Use w-5 h-5 or w-4 h-4 across your application for visual harmony
• Color inheritance: Icons automatically inherit text color via currentColor
• Library agnostic: Works with any icon library (Heroicons, Lucide, Phosphor, etc.) or inline SVG
• Optional everywhere: All icon snippets are optional - components work perfectly without them

Active State Support

Navbar and Sidebar components now automatically style active navigation items:

• Add the active class to links/buttons for current page indication
• Or use the new currentPath prop for automatic active state management (see Layout Best Practices)
• How currentPath works: Components scan for <a> and <button> elements, match their href or data-href attribute against currentPath, and automatically add/remove the active class
• Manual classes preserved: Manually applied active classes take precedence and are never removed by automatic management
• Falsy currentPath: When currentPath becomes falsy, only auto-managed active classes are cleared
• Button support: Buttons need a data-href attribute to participate in automatic active state (e.g., <button data-href="/action">Action</button>)
• Navbar: Shows accent color with underline indicator
• Sidebar: Shows accent background, left border, and glow effect
• Works seamlessly with SvelteKit's page stores or manual state management

Improved Layout Management

Automatic Sidebar Positioning - Sidebar now automatically detects Navbar presence and adjusts its top position to start just below the Navbar. Zero configuration needed!

How it works:

• Sidebar uses a data-navbar attribute selector to find the Navbar element
• Reads the Navbar's offsetHeight and dynamically sets its own top style property
• A ResizeObserver watches for Navbar height changes (responsive behavior, window resize)
• When Navbar is absent, Sidebar starts from the top (top: 0)

Z-index layering ensures proper visual hierarchy:

• Navbar: z-50 (highest, sits on top)
• Sidebar: z-40 (below navbar, above content)
• Modals, tooltips, overlays: z-50+ (above everything)

Example - Zero Configuration:

<script>
  let sidebarOpen = $state(true);
</script>

<!-- Navbar automatically gets data-navbar attribute -->
<Navbar position="sticky" height="md">
  {#snippet toggleButton()}
    <IconButton variant="ghost" onclick={() => sidebarOpen = !sidebarOpen}>
      <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16" />
      </svg>
    </IconButton>
  {/snippet}
  
  {#snippet logo()}
    <span>MyApp</span>
  {/snippet}
  
  {#snippet navigation()}
    <a href="/">Home</a>
    <a href="/about">About</a>
  {/snippet}
  
  {#snippet actions()}
    <Button variant="primary">Sign In</Button>
  {/snippet}
</Navbar>

<!-- Sidebar automatically detects Navbar and positions below it -->
<Sidebar bind:open={sidebarOpen} side="left" width="md">
  <!-- Sidebar content -->
</Sidebar>

<!-- No manual margin-top needed on Sidebar! -->

Responsive behavior: The Sidebar's positioning updates automatically when the Navbar height changes (e.g., responsive breakpoints, content changes). This ensures consistent layout across all screen sizes.

📚 Components

Buttons

Button - Primary interactive element with variants

<script>
  import { Button } from '@mrintel/villain-ui';
</script>

<Button variant="primary" size="md">Primary Button</Button>
<Button variant="secondary" size="md">Secondary Button</Button>
<Button variant="ghost" size="sm">Ghost Button</Button>
<Button variant="primary" size="lg" disabled>Disabled</Button>

<!-- Simple icon usage -->
<Button variant="primary">
  {#snippet iconBefore()}
    <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
    </svg>
  {/snippet}
  Add Item
</Button>

<!-- Icon after text -->
<Button variant="secondary">
  Download
  {#snippet iconAfter()}
    <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4" />
    </svg>
  {/snippet}
</Button>

<!-- Advanced: Different icons before and after -->
<Button variant="primary">
  {#snippet iconBefore()}
    <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z" />
    </svg>
  {/snippet}
  Upload Photo
  {#snippet iconAfter()}
    <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
    </svg>
  {/snippet}
</Button>

IconButton - Compact button for icon-only interactions

<script>
  import { IconButton } from '@mrintel/villain-ui';
</script>

<IconButton variant="primary" size="md" ariaLabel="Settings">
  <SettingsIcon />
</IconButton>

Props:

• variant?: 'primary' | 'secondary' | 'ghost' - Button style variant
• size?: 'sm' | 'md' | 'lg' - Button size
• ariaLabel: string - Accessibility label (required for screen readers)
• disabled?: boolean - Disable button interaction

ButtonGroup - Group related buttons together

<script>
  import { ButtonGroup, Button } from '@mrintel/villain-ui';
</script>

<ButtonGroup>
  <Button variant="secondary">Left</Button>
  <Button variant="secondary">Center</Button>
  <Button variant="secondary">Right</Button>
</ButtonGroup>

LinkButton - Button styled as link

<script>
  import { LinkButton } from '@mrintel/villain-ui';
</script>

<LinkButton href="/docs" variant="primary">View Documentation</LinkButton>

Icon Examples:

<!-- LinkButton with icon before text -->
<LinkButton href="/docs" variant="primary">
  {#snippet iconBefore()}
    <BookOpenIcon class="w-5 h-5" />
  {/snippet}
  View Documentation
</LinkButton>

<!-- LinkButton with icon after text -->
<LinkButton href="/download" variant="secondary">
  Download
  {#snippet iconAfter()}
    <DownloadIcon class="w-5 h-5" />
  {/snippet}
</LinkButton>

<!-- LinkButton with different icons before and after -->
<LinkButton href="/external" variant="ghost" target="_blank">
  {#snippet iconBefore()}
    <ExternalLinkIcon class="w-4 h-4" />
  {/snippet}
  External Link
  {#snippet iconAfter()}
    <ArrowRightIcon class="w-4 h-4" />
  {/snippet}
</LinkButton>

FloatingActionButton - Prominent floating action button

<script>
  import { FloatingActionButton } from '@mrintel/villain-ui';
</script>

<FloatingActionButton 
  position="bottom-right" 
  ariaLabel="Create new item"
  onclick={() => console.log('FAB clicked')}
>
  <PlusIcon />
</FloatingActionButton>

Props:

• position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' - FAB position on screen
• ariaLabel: string - Accessibility label (required for screen readers)
• onclick?: () => void - Click handler
• disabled?: boolean - Disable button interaction

Forms

Input - Text input with label and error states

<script>
  import { Input } from '@mrintel/villain-ui';
  
  let email = $state('');
  let hasError = $state(false);
</script>

<Input 
  type="email" 
  label="Email Address" 
  placeholder="[email protected]"
  bind:value={email}
  error={hasError}
/>

Icon Examples:

<!-- Input with icon before (search) -->
<Input 
  type="text" 
  label="Search" 
  placeholder="Search..."
  bind:value={searchQuery}
>
  {#snippet iconBefore()}
    <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
    </svg>
  {/snippet}
</Input>

<!-- Input with icon after (password visibility toggle) -->
<Input 
  type="password" 
  label="Password" 
  bind:value={password}
>
  {#snippet iconAfter()}
    <button onclick={togglePasswordVisibility}>
      <EyeIcon class="w-5 h-5" />
    </button>
  {/snippet}
</Input>

<!-- Input with email icon -->
<Input 
  type="email" 
  label="Email" 
  bind:value={email}
>
  {#snippet iconBefore()}
    <MailIcon class="w-5 h-5" />
  {/snippet}
</Input>

Textarea - Multi-line text input

<script>
  import { Textarea } from '@mrintel/villain-ui';
  
  let comment = $state('');
</script>

<Textarea 
  label="Comment" 
  placeholder="Enter your comment..."
  rows={5}
  bind:value={comment}
/>

Icon Example:

<Textarea 
  label="Message" 
  rows={5}
  bind:value={message}
>
  {#snippet iconBefore()}
    <MessageIcon class="w-5 h-5" />
  {/snippet}
</Textarea>

Note: Textarea only supports iconBefore snippet, positioned at top-left of the text area.

Select - Dropdown selection

<script>
  import { Select } from '@mrintel/villain-ui';
  
  let selected = $state('');
  const options = [
    { value: 'option1', label: 'Option 1' },
    { value: 'option2', label: 'Option 2' },
    { value: 'option3', label: 'Option 3' }
  ];
</script>

<Select label="Choose an option" {options} bind:value={selected} />

Icon Example:

<Select 
  label="Country" 
  {options} 
  bind:value={selectedCountry}
>
  {#snippet iconBefore()}
    <GlobeIcon class="w-5 h-5" />
  {/snippet}
</Select>

Note: Select only supports iconBefore snippet, positioned at the left side with automatic padding.

Checkbox - Boolean selection

<script>
  import { Checkbox } from '@mrintel/villain-ui';
  
  let accepted = $state(false);
</script>

<Checkbox label="I accept the terms and conditions" bind:checked={accepted} />

Icon Example:

<Checkbox bind:checked={accepted}>
  {#snippet iconBefore()}
    <ShieldCheckIcon class="w-4 h-4" />
  {/snippet}
  I accept the terms and conditions
</Checkbox>

Switch - Toggle switch

<script>
  import { Switch } from '@mrintel/villain-ui';
  
  let enabled = $state(false);
</script>

<Switch label="Enable notifications" bind:checked={enabled} />

Icon Example:

<Switch bind:checked={darkMode}>
  {#snippet iconBefore()}
    <MoonIcon class="w-4 h-4" />
  {/snippet}
  Dark Mode
</Switch>

RadioGroup - Single selection from multiple options

<script>
  import { RadioGroup } from '@mrintel/villain-ui';
  
  let selected = $state('');
  const options = [
    { value: 'small', label: 'Small' },
    { value: 'medium', label: 'Medium' },
    { value: 'large', label: 'Large' }
  ];
</script>

<RadioGroup label="Select size" {options} bind:value={selected} />

Icon Example:

<script>
  import { RadioGroup } from '@mrintel/villain-ui';
  import { CreditCardIcon, PayPalIcon } from 'your-icon-library';
  
  const options = [
    { 
      value: 'card', 
      label: 'Credit Card',
      iconBefore: CreditCardIcon // Snippet reference
    },
    { 
      value: 'paypal', 
      label: 'PayPal',
      iconBefore: PayPalIcon // Snippet reference
    }
  ];
</script>

<RadioGroup 
  label="Payment Method" 
  {options} 
  bind:value={paymentMethod} 
/>

RangeSlider - Numeric range selection

<script>
  import { RangeSlider } from '@mrintel/villain-ui';
  
  let volume = $state(50);
</script>

<RangeSlider label="Volume" min={0} max={100} bind:value={volume} />

FileUpload - File selection with drag & drop

<script>
  import { FileUpload } from '@mrintel/villain-ui';
  
  function handleUpload(files) {
    console.log('Files:', files);
  }
</script>

<FileUpload 
  accept="image/*" 
  multiple 
  onchange={handleUpload}
  label="Upload Images"
/>

Icon Example:

<FileUpload 
  bind:files={uploadedFiles}
  accept="image/*"
>
  {#snippet icon()}
    <CloudUploadIcon class="w-8 h-8" />
  {/snippet}
</FileUpload>

Note: FileUpload uses a simple icon snippet (not iconBefore) to replace the default upload icon.

InputGroup - Grouped input with addons

<script>
  import { InputGroup } from '@mrintel/villain-ui';
</script>

<InputGroup>
  {#snippet prepend()}
    https://
  {/snippet}
  
  <input type="text" placeholder="example.com" />
  
  {#snippet append()}
    .com
  {/snippet}
</InputGroup>

DatePicker - Date input with native date picker

<script>
  import { DatePicker } from '@mrintel/villain-ui';

  let selectedDate = $state('');
</script>

<DatePicker
  label="Select Date"
  bind:value={selectedDate}
  min="2024-01-01"
  max="2024-12-31"
/>

Props:

• value?: string - Selected date in YYYY-MM-DD format (bindable)
• label?: string - Input label
• min?: string - Minimum selectable date
• max?: string - Maximum selectable date
• placeholder?: string - Placeholder text
• disabled?: boolean - Disable date selection
• error?: boolean - Show error state
• class?: string - Additional CSS classes

TimePicker - Time input with native time picker

<script>
  import { TimePicker } from '@mrintel/villain-ui';

  let selectedTime = $state('');
</script>

<TimePicker
  label="Select Time"
  bind:value={selectedTime}
  step={900}
/>

Props:

• value?: string - Selected time in HH:MM format (bindable)
• label?: string - Input label
• min?: string - Minimum selectable time
• max?: string - Maximum selectable time
• step?: number - Time interval in seconds (e.g., 900 = 15 minutes)
• placeholder?: string - Placeholder text
• disabled?: boolean - Disable time selection
• error?: boolean - Show error state
• class?: string - Additional CSS classes

DateTimePicker - Combined date and time input

<script>
  import { DateTimePicker } from '@mrintel/villain-ui';

  let selectedDateTime = $state('');
</script>

<DateTimePicker
  label="Select Date & Time"
  bind:value={selectedDateTime}
  min="2024-01-01T00:00"
  max="2024-12-31T23:59"
/>

Props:

• value?: string - Selected date-time in ISO format (bindable)
• label?: string - Input label
• min?: string - Minimum selectable date-time
• max?: string - Maximum selectable date-time
• step?: number - Time interval in seconds
• placeholder?: string - Placeholder text
• disabled?: boolean - Disable date-time selection
• error?: boolean - Show error state
• class?: string - Additional CSS classes

Layout

Card - Content container with optional header and footer

<script>
  import { Card } from '@mrintel/villain-ui';
</script>

<Card padding="lg" hoverable>
  {#snippet header()}
    <h2>Card Title</h2>
  {/snippet}
  
  <p>Card content goes here with beautiful glass morphism effect.</p>
  
  {#snippet footer()}
    <Button variant="primary">Action</Button>
  {/snippet}
</Card>

<!-- Card as a link with lift effect and icon -->
<Card href="/features" class="hover-lift" padding="lg">
  {#snippet iconBefore()}
    <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z" />
    </svg>
  {/snippet}

  <h3>Feature Name</h3>
  <p>Clickable card with hover lift effect.</p>
</Card>

Props:

• href?: string - Makes the card a clickable link (renders as <a> tag)
• target?: string - Link target attribute (e.g., '_blank')
• rel?: string - Link rel attribute (defaults to 'noopener noreferrer' for target='_blank')
• padding?: 'none' | 'sm' | 'md' | 'lg' - Internal padding (default: 'md')
• iconBefore?: Snippet - Optional icon displayed with .card-icon utility
• header?: Snippet - Optional header content
• footer?: Snippet - Optional footer content
• children?: Snippet - Main card content
• class?: string - Additional CSS classes

Note: For clickable cards with hover effects, use href to make the card a link and add class="hover-lift" to enable the lift animation. The iconBefore snippet uses the .card-icon utility class for centered, accent-colored icon display.

Panel - Simple content panel

<script>
  import { Panel } from '@mrintel/villain-ui';
</script>

<!-- Recommended: Use variant prop for styling -->
<Panel variant="glass" padding="lg">
  <p>Enhanced glass morphism panel</p>
</Panel>

<!-- Default panel with basic glass styling -->
<Panel>
  <p>Panel content with default styling</p>
</Panel>

<!-- Legacy: glass prop (deprecated, use variant='glass' instead) -->
<Panel glass={false}>
  <p>Solid background panel (backwards compatible)</p>
</Panel>

Panel Props:

• variant?: 'default' | 'glass' - Primary styling selector. Use 'glass' for enhanced glass morphism with accent glow.
• padding?: 'none' | 'sm' | 'md' | 'lg' - Internal padding (default: 'md')
• rounded?: boolean - Apply rounded corners (default: true)
• glass?: boolean - Deprecated. Use variant='glass' instead. Only affects variant='default' for backwards compatibility.
• class?: string - Additional CSS classes

Grid - Responsive grid layout

<script>
  import { Grid, Card } from '@mrintel/villain-ui';
</script>

<Grid columns={3} gap="lg">
  <Card>Item 1</Card>
  <Card>Item 2</Card>
  <Card>Item 3</Card>
</Grid>

Container - Centered content container

<script>
  import { Container } from '@mrintel/villain-ui';
</script>

<Container maxWidth="lg">
  <h1>Centered Content</h1>
</Container>

SectionHeader - Section heading with divider

<script>
  import { SectionHeader } from '@mrintel/villain-ui';
</script>

<SectionHeader title="Features" subtitle="What makes us different" />

Divider - Visual separator

<script>
  import { Divider } from '@mrintel/villain-ui';
</script>

<Divider />
<Divider orientation="vertical" />

Navigation

Navbar - Top navigation bar

<script>
  import { Navbar, Button, IconButton } from '@mrintel/villain-ui';
  import { page } from '$app/stores';
  
  let sidebarOpen = $state(false);
  let currentPath = $derived($page.url.pathname);
</script>

<Navbar {currentPath}>
  {#snippet toggleButton()}
    <IconButton variant="ghost" size="sm" onclick={() => sidebarOpen = !sidebarOpen}>
      <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16" />
      </svg>
    </IconButton>
  {/snippet}
  
  {#snippet logo()}
    <span style="color: var(--color-accent)">MyApp</span>
  {/snippet}
  
  {#snippet navigation()}
    <a href="/">Home</a>
    <a href="/about">About</a>
    <a href="/contact">Contact</a>
  {/snippet}
  
  {#snippet actions()}
    <Button variant="primary">Sign In</Button>
  {/snippet}
</Navbar>

Props:

• position?: 'sticky' | 'fixed' - Navbar positioning (default: 'sticky')
• height?: 'sm' | 'md' | 'lg' - Navbar height (default: 'md')
• navigationAlign?: 'left' | 'center' - Navigation alignment (default: 'center')
• toggleButton?: Snippet - Toggle button slot (typically for sidebar/mobile menu)
• logo?: Snippet - Logo content snippet
• navigation?: Snippet - Primary navigation links slot
• actions?: Snippet - Action buttons or profile controls slot
• children?: Snippet - Fallback navigation content (used if navigation not provided)
• currentPath?: string - Current route path for automatic active state highlighting

Note: The currentPath prop enables automatic active state management. Links matching the current path will receive the active class automatically.

Sidebar - Side navigation with collapsible state

<script>
  import { Sidebar } from '@mrintel/villain-ui';
  import { page } from '$app/stores';
  
  let open = $state(true);
  let currentPath = $derived($page.url.pathname);
</script>

<Sidebar bind:open {currentPath}>
  {#snippet header()}
    <div>App Name</div>
  {/snippet}
  
  <!-- Recommended markup pattern for predictable collapsed behavior -->
  <a href="/dashboard">
    <span class="sidebar-item-icon">
      <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" />
      </svg>
    </span>
    <span class="sidebar-item-label">Dashboard</span>
  </a>
  
  <a href="/settings">
    <span class="sidebar-item-icon">
      <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" />
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z" />
      </svg>
    </span>
    <span class="sidebar-item-label">Settings</span>
  </a>
  
  <!-- Items without icons will show first letter in collapsed mode -->
  <a href="/profile">
    <span class="sidebar-item-label">Profile</span>
  </a>
</Sidebar>

Props:

• open?: boolean (bindable) - Sidebar open/collapsed state (default: true)
• side?: 'left' | 'right' - Sidebar position (default: 'left')
• width?: 'sm' | 'md' | 'lg' - Sidebar width when open (default: 'md')
• header?: Snippet - Header content snippet
• children?: Snippet - Sidebar navigation content
• currentPath?: string - Current route path for automatic active state highlighting

Collapsed Mode Behavior:

• Items with .sidebar-item-icon will show the icon centered when collapsed
• Items without icons will show the first letter of .sidebar-item-label (or text content) in a circular badge
• Use .sidebar-item-icon and .sidebar-item-label classes for predictable behavior
• currentPath?: string - Current route path for automatic active state highlighting

Collapsed State Behavior:

When open={false}, the sidebar automatically adapts its display:

• Items with icons: Shows centered icons (enlarged to 1.5rem) with text hidden
• Items without icons: Shows first letter in an accent-colored circle as a fallback
• Header: Remains visible with reduced padding and centered text

The component automatically detects icons by looking for <svg>, [class*="icon"], or [data-icon] elements. All transitions use smooth animations with var(--ease-luxe).

Active State Management

Navigation components (Navbar, Sidebar) support automatic active state highlighting via the currentPath prop. Pass the current route path, and the component will automatically add the active class to matching links and buttons based on href or data-href attributes. This eliminates manual active class management.

Example:

<script>
  import { page } from '$app/stores'; // SvelteKit
  let currentPath = $derived($page.url.pathname);
</script>

<Navbar {currentPath}>
  <a href="/">Home</a>
  <a href="/about">About</a>
</Navbar>

The component matches exact paths and nested routes (e.g., /buttons matches /buttons/icon-button).

Tabs - Tabbed interface

<script>
  import { Tabs } from '@mrintel/villain-ui';
  
  let activeTab = $state('tab1');
  const tabs = [
    { 
      id: 'tab1', 
      label: 'Overview',
      iconBefore: OverviewIcon // Snippet reference
    },
    { id: 'tab2', label: 'Analytics' },
    { id: 'tab3', label: 'Reports' }
  ];
</script>

<Tabs {tabs} bind:activeTab ontabchange={(newTab) => console.log('Tab changed:', newTab)}>
  {#if activeTab === 'tab1'}
    <div>Overview content</div>
  {:else if activeTab === 'tab2'}
    <div>Analytics content</div>
  {:else}
    <div>Reports content</div>
  {/if}
</Tabs>

Keyboard Navigation:

• Arrow Left/Right (horizontal) or Up/Down (vertical): Navigate between tabs
• Home: Jump to first tab
• End: Jump to last tab
• Tab: Move focus out of tab list

Accessibility Features:

• ARIA: role="tablist", role="tab", aria-selected, aria-disabled
• Roving tabindex: Only active tab is focusable (tabindex="0")
• Screen readers: Tab labels announced with selection state
• Focus management: Arrow keys change both focus and selection

Breadcrumbs - Navigation breadcrumb trail

<script>
  import { Breadcrumbs } from '@mrintel/villain-ui';
  
  const items = [
    { label: 'Home', href: '/' },
    { label: 'Products', href: '/products' },
    { label: 'Category', href: '/products/category' },
    { label: 'Item' }
  ];
</script>

<Breadcrumbs {items} />

Icon Example:

<script>
  import { Breadcrumbs } from '@mrintel/villain-ui';
  import { HomeIcon, FolderIcon, DocumentIcon } from 'your-icon-library';
  
  const items = [
    { 
      label: 'Home', 
      href: '/',
      icon: HomeIcon // Snippet reference
    },
    { 
      label: 'Projects', 
      href: '/projects',
      icon: FolderIcon // Snippet reference
    },
    { 
      label: 'Document',
      icon: DocumentIcon // Snippet reference
    }
  ];
</script>

<Breadcrumbs {items} />

Menu - Vertical navigation menu

<script>
  import { Menu } from '@mrintel/villain-ui';
  
  const items = [
    { 
      id: 'dashboard',
      label: 'Dashboard', 
      icon: DashboardIcon, // Snippet reference
      onclick: () => goto('/dashboard')
    },
    { 
      id: 'settings',
      label: 'Settings', 
      icon: SettingsIcon, // Snippet reference
      onclick: () => goto('/settings')
    }
  ];
</script>

<Menu {items} />

Props:

• items?: MenuItem[] - Array of menu items
• children?: Snippet - Alternative to items array for custom content

MenuItem Interface:

• id: string - Unique identifier
• label: string - Display text
• icon?: Snippet - Optional icon snippet (not iconBefore)
• disabled?: boolean - Disable item
• onclick?: () => void - Click handler

Keyboard Navigation:

• Arrow Down/Up: Navigate menu items (wraps around)
• Home: Jump to first item
• End: Jump to last item
• Enter/Space: Activate selected item
• Escape: Close menu (if in a dropdown/context menu)

Accessibility Features:

• ARIA: role="menu", role="menuitem"
• Roving tabindex: Only selected item is focusable
• Screen readers: Menu items announced with disabled state

DropdownMenu - Dropdown menu with items

<script>
  import { DropdownMenu, Button } from '@mrintel/villain-ui';
  import { EditIcon, TrashIcon } from 'your-icon-library';
  
  const items = [
    { 
      id: 'edit', 
      label: 'Edit', 
      icon: EditIcon, // Snippet reference
      onclick: () => console.log('Edit') 
    },
    { 
      id: 'delete', 
      label: 'Delete', 
      icon: TrashIcon, // Snippet reference
      onclick: () => console.log('Delete'),
      disabled: false
    }
  ];
</script>

<DropdownMenu {items}>
  {#snippet trigger()}
    <Button>Options</Button>
  {/snippet}
</DropdownMenu>

Props:

• items: MenuItem[] - Array of menu items
• open?: boolean (bindable) - Dropdown open state
• placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end' - Menu position
• trigger?: Snippet - Trigger button content

MenuItem Interface:

• id: string - Unique identifier
• label: string - Display text
• icon?: Snippet - Optional icon snippet
• disabled?: boolean - Disable item
• onclick?: () => void - Click handler

Keyboard Navigation:

• Arrow Down/Up: Navigate menu items (wraps around)
• Home: Jump to first item
• End: Jump to last item
• Enter/Space: Activate selected item
• Escape: Close menu

Accessibility Features:

• ARIA: role="menu", role="menuitem", aria-haspopup, aria-expanded, aria-controls
• Auto-focus: First item focused on open
• Roving tabindex: Only selected item is focusable
• Click outside: Closes menu when clicking outside
• Screen readers: Menu state and items announced clearly

ContextMenu - Right-click context menu

<script>
  import { ContextMenu } from '@mrintel/villain-ui';
  import { CopyIcon, PasteIcon } from 'your-icon-library';
  
  const items = [
    { 
      id: 'copy', 
      label: 'Copy', 
      icon: CopyIcon, // Snippet reference
      onclick: () => console.log('Copy') 
    },
    { 
      id: 'paste', 
      label: 'Paste', 
      icon: PasteIcon, // Snippet reference
      onclick: () => console.log('Paste') 
    }
  ];
</script>

<ContextMenu {items}>
  {#snippet trigger()}
    <div>Right click me</div>
  {/snippet}
</ContextMenu>

Props:

• items: MenuItem[] - Array of menu items
• open?: boolean (bindable) - Context menu open state
• x?: number (bindable) - Menu X position
• y?: number (bindable) - Menu Y position
• trigger?: Snippet - Content that triggers context menu on right-click

MenuItem Interface:

• id: string - Unique identifier
• label: string - Display text
• icon?: Snippet - Optional icon snippet
• disabled?: boolean - Disable item
• onclick?: () => void - Click handler

Keyboard Navigation:

• Arrow Down/Up: Navigate menu items (wraps around)
• Home: Jump to first item
• End: Jump to last item
• Enter/Space: Activate selected item
• Escape: Close menu

Accessibility Features:

• ARIA: role="menu", role="menuitem", aria-haspopup
• Auto-focus: First item focused on open
• Roving tabindex: Only selected item is focusable
• Click outside: Closes menu when clicking outside
• Screen readers: Menu state and items announced clearly

Overlays & Feedback

Modal - Modal dialog with backdrop

<script>
  import { Modal, Button } from '@mrintel/villain-ui';
  
  let open = $state(false);
</script>

<Button onclick={() => open = true}>Open Modal</Button>

<Modal bind:open title="Confirm Action">
  <p>Are you sure you want to proceed?</p>
  
  {#snippet footer()}
    <Button variant="ghost" onclick={() => open = false}>Cancel</Button>
    <Button variant="primary" onclick={() => open = false}>Confirm</Button>
  {/snippet}
</Modal>

Icon Example:

<script>
  import { Modal, Button } from '@mrintel/villain-ui';
  import { ExclamationTriangleIcon } from 'your-icon-library';
  
  let open = $state(false);
</script>

<Button onclick={() => open = true}>Delete Item</Button>

<Modal bind:open title="Confirm Deletion">
  {#snippet iconBefore()}
    <ExclamationTriangleIcon class="w-6 h-6 text-error" />
  {/snippet}
  
  <p>Are you sure you want to delete this item? This action cannot be undone.</p>
  
  {#snippet footer()}
    <Button variant="ghost" onclick={() => open = false}>Cancel</Button>
    <Button variant="primary" onclick={() => { deleteItem(); open = false; }}>Delete</Button>
  {/snippet}
</Modal>

Props:

• open?: boolean (bindable) - Modal open state
• title?: string - Modal title text
• iconBefore?: Snippet - Optional icon displayed before title
• closeOnEscape?: boolean - Close modal on Escape key (default: true)
• closeOnBackdrop?: boolean - Close modal on backdrop click (default: true)
• footer?: Snippet - Optional footer content
• children?: Snippet - Main modal content

Accessibility Features:

• Focus trap: Tab/Shift+Tab cycles within modal
• Escape key: Closes modal (if closeOnEscape=true)
• Auto-focus: First interactive element focused on open
• Focus restoration: Returns focus to trigger element on close
• ARIA: role="dialog", aria-modal="true", aria-labelledby
• Screen readers: Modal title and content announced

Alert - Alert message with variants

<script>
  import { Alert } from '@mrintel/villain-ui';
</script>

<Alert variant="success" title="Success">
  Operation completed successfully!
</Alert>

<Alert variant="warning" title="Warning">
  Please review your changes.
</Alert>

<Alert variant="error" title="Error">
  An error occurred.
</Alert>

<!-- With custom icon -->
<Alert variant="info" title="Custom Icon">
  {#snippet iconBefore()}
    <svg class="w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
      <path d="M10 12a2 2 0 100-4 2 2 0 000 4z"/>
      <path fill-rule="evenodd" d="M.458 10C1.732 5.943 5.522 3 10 3s8.268 2.943 9.542 7c-1.274 4.057-5.064 7-9.542 7S1.732 14.057.458 10zM14 10a4 4 0 11-8 0 4 4 0 018 0z" clip-rule="evenodd"/>
    </svg>
  {/snippet}
  This alert uses a custom icon snippet.
</Alert>

Props:

• variant?: 'success' | 'warning' | 'error' | 'info' - Alert style variant
• title: string - Alert title text
• iconBefore?: Snippet - Optional custom icon (overrides default variant icon)
• dismissible?: boolean - Show close button (default: false)
• onclose?: () => void - Callback when alert is dismissed
• children?: Snippet - Alert content

Accessibility Features:

• ARIA: role="status" (info/success) or role="alert" (warning/error)
• aria-live: "polite" (info/success/warning) or "assertive" (error)
• Dismissible: Close button has aria-label="Dismiss alert"
• Screen readers: Alert content announced based on severity

Spinner - Loading spinner

<script>
  import { Spinner } from '@mrintel/villain-ui';
</script>

<Spinner size="lg" />

Tooltip - Hover tooltip

<script>
  import { Tooltip } from '@mrintel/villain-ui';
</script>

<Tooltip content="This is a helpful tip" position="top">
  <Button>Hover me</Button>
</Tooltip>

ProgressBar - Progress indicator

<script>
  import { ProgressBar } from '@mrintel/villain-ui';
  
  let progress = $state(45);
</script>

<ProgressBar value={progress} max={100} showLabel />

SkeletonLoader - Content loading placeholder

<script>
  import { SkeletonLoader } from '@mrintel/villain-ui';
</script>

<SkeletonLoader variant="text" count={3} />
<SkeletonLoader variant="circle" width="60px" height="60px" />
<SkeletonLoader variant="rectangle" width="100%" height="200px" />

Toast - Notification toast

<script>
  import { Toast } from '@mrintel/villain-ui';
  
  let show = $state(false);
</script>

<Toast bind:show variant="success" duration={3000}>
  Changes saved successfully!
</Toast>

Icon Examples:

<script>
  import { Toast } from '@mrintel/villain-ui';
  import { CheckCircleIcon, XCircleIcon, InformationCircleIcon } from 'your-icon-library';
  
  let showSuccess = $state(false);
  let showError = $state(false);
  let showInfo = $state(false);
</script>

<!-- Success toast with custom icon -->
<Toast bind:show={showSuccess} variant="success" duration={3000}>
  {#snippet iconBefore()}
    <CheckCircleIcon class="w-5 h-5" />
  {/snippet}
  Changes saved successfully!
</Toast>

<!-- Error toast with custom icon -->
<Toast bind:show={showError} variant="error" duration={5000}>
  {#snippet iconBefore()}
    <XCircleIcon class="w-5 h-5" />
  {/snippet}
  Failed to save changes. Please try again.
</Toast>

<!-- Info toast with custom icon -->
<Toast bind:show={showInfo} variant="info">
  {#snippet iconBefore()}
    <InformationCircleIcon class="w-5 h-5" />
  {/snippet}
  New features available! Check them out.
</Toast>

Drawer - Slide-out drawer panel

<script>
  import { Drawer, Button } from '@mrintel/villain-ui';
  
  let open = $state(false);
</script>

<Button onclick={() => open = true}>Open Drawer</Button>

<Drawer bind:open position="right">
  <h2>Drawer Content</h2>
  <p>This slides in from the side.</p>
</Drawer>

Icon Example:

<script>
  import { Drawer, Button } from '@mrintel/villain-ui';
  import { Cog6ToothIcon } from 'your-icon-library';
  
  let open = $state(false);
</script>

<Button onclick={() => open = true}>Open Settings</Button>

<Drawer bind:open position="right" title="Settings">
  {#snippet iconBefore()}
    <Cog6ToothIcon class="w-6 h-6" />
  {/snippet}
  
  <div class="space-y-4">
    <h3>Application Settings</h3>
    <p>Configure your preferences here.</p>
    <!-- Settings content -->
  </div>
</Drawer>

Props:

• open?: boolean (bindable) - Drawer open state
• side?: 'left' | 'right' | 'top' | 'bottom' - Drawer slide-in position (default: 'right')
• title?: string - Drawer title text
• iconBefore?: Snippet - Optional icon displayed before title
• closeOnEscape?: boolean - Close drawer on Escape key (default: true)
• closeOnBackdrop?: boolean - Close drawer on backdrop click (default: true)
• children?: Snippet - Main drawer content

Accessibility Features:

• Focus trap: Tab/Shift+Tab cycles within drawer
• Escape key: Closes drawer (if closeOnEscape=true)
• Auto-focus: First interactive element focused on open
• Focus restoration: Returns focus to trigger element on close
• ARIA: role="dialog", aria-modal="true", aria-labelledby
• Screen readers: Drawer title and content announced

Popover - Popover content

<script>
  import { Popover } from '@mrintel/villain-ui';
</script>

<Popover>
  {#snippet trigger()}
    <Button>Click me</Button>
  {/snippet}
  
  {#snippet content()}
    <div>Popover content here</div>
  {/snippet}
</Popover>

Dropdown - Generic dropdown container

<script>
  import { Dropdown } from '@mrintel/villain-ui';
</script>

<Dropdown trigger="Select Option">
  <a href="#">Option 1</a>
  <a href="#">Option 2</a>
  <a href="#">Option 3</a>
</Dropdown>

CommandPalette - Command palette with fuzzy search

<script>
  import { CommandPalette } from '@mrintel/villain-ui';
  
  let open = $state(false);
  const commands = [
    { id: '1', label: 'New File', onSelect: () => console.log('New File') },
    { id: '2', label: 'Open Settings', onSelect: () => console.log('Settings') },
    { id: '3', label: 'Search Files', onSelect: () => console.log('Search') }
  ];
</script>

<CommandPalette bind:open {commands} placeholder="Search commands..." />

Keyboard Navigation:

• Arrow Down/Up: Navigate command list
• Enter: Execute selected command
• Escape: Close palette
• Type to search: Fuzzy search filters commands in real-time

Accessibility Features:

• ARIA: role="combobox", aria-expanded, aria-haspopup, aria-controls, aria-activedescendant
• Auto-focus: Search input focused on open
• Keyboard navigation: Arrow keys navigate filtered results, Enter executes command
• Screen readers: Command count and selected command announced via aria-activedescendant

### Typography

**Heading** - Semantic heading levels

```svelte
<script>
  import { Heading } from '@mrintel/villain-ui';
</script>

<Heading level={1}>Main Title</Heading>
<Heading level={2}>Section Title</Heading>
<Heading level={3}>Subsection</Heading>

<!-- Gradient variant for hero and section titles -->
<Heading level={1} variant="gradient">Hero Title with Gradient</Heading>
<Heading level={2} variant="gradient" glow>Section with Gradient and Glow</Heading>

Props:

• level: 1 | 2 | 3 | 4 | 5 | 6 - Semantic heading level (required)
• variant?: 'gradient' - Apply gradient styling using the .text-gradient utility
• glow?: boolean - Add text glow effect (works well with gradient variant)
• class?: string - Additional CSS classes

Note: The gradient variant applies the .text-gradient utility class, creating a purple-to-soft-purple gradient effect. Combine with glow for enhanced visual impact on hero sections.

Text - Text with variants

<script>
  import { Text } from '@mrintel/villain-ui';
</script>

<Text variant="body">Regular body text</Text>
<Text variant="caption">Caption text</Text>
<Text variant="muted">Muted text</Text>

Code - Inline code

<script>
  import { Code } from '@mrintel/villain-ui';
</script>

<p>Install with <Code>npm install @mrintel/villain-ui</Code></p>

Data Display

Table - Data table with sorting, filtering, and custom rendering

<script>
  import { Table, type TableColumn, type SortDirection } from '@mrintel/villain-ui';

  const columns: TableColumn[] = [
    { key: 'name', label: 'Name', sortable: true },
    { key: 'email', label: 'Email', sortable: true },
    { key: 'role', label: 'Role', align: 'center' },
    {
      key: 'status',
      label: 'Status',
      render: (value) => `<span class="badge-${value}">${value}</span>`
    }
  ];

  let allData = [
    { name: 'John Doe', email: '[email protected]', role: 'Admin', status: 'active' },
    { name: 'Jane Smith', email: '[email protected]', role: 'User', status: 'active' },
    { name: 'Bob Johnson', email: '[email protected]', role: 'User', status: 'inactive' }
  ];

  let data = $state([...allData]);
  let searchQuery = $state('');

  // User-defined filter function
  const filterFn = (row: Record<string, any>) => {
    if (!searchQuery) return true;
    const query = searchQuery.toLowerCase();
    return (
      row.name.toLowerCase().includes(query) ||
      row.email.toLowerCase().includes(query) ||
      row.role.toLowerCase().includes(query)
    );
  };

  // User-defined sort handler
  function handleSort(columnKey: string, direction: SortDirection) {
    if (!direction) {
      data = [...allData];
      return;
    }

    data = [...data].sort((a, b) => {
      const aVal = a[columnKey];
      const bVal = b[columnKey];
      const modifier = direction === 'asc' ? 1 : -1;
      return aVal > bVal ? modifier : aVal < bVal ? -modifier : 0;
    });
  }

  // User-defined row click handler
  function handleRowClick(row: Record<string, any>) {
    console.log('Clicked row:', row);
  }
</script>

<input type="text" bind:value={searchQuery} placeholder="Search..." />

<Table
  {columns}
  {data}
  {filterFn}
  onSort={handleSort}
  onRowClick={handleRowClick}
  loading={isLoading}
  loadingMessage="Loading data..."
  emptyMessage="No results found"
  stickyHeader
  hoverable
  striped
/>

<!-- Custom empty state -->
<Table {columns} {data} striped>
  {#snippet emptyState()}
    <div>
      <h3>No data yet</h3>
      <p>Add your first item to get started</p>
      <button>Add Item</button>
    </div>
  {/snippet}
</Table>

<!-- Manual markup mode still supported -->
<Table striped hoverable>
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>John</td>
      <td>[email protected]</td>
    </tr>
  </tbody>
</Table>

<!-- Table Features -->
Props:
- filterFn: (row) => boolean - User-defined filter/search function
- onSort: (columnKey, direction) => void - Sort callback
- onRowClick: (row) => void - Row click callback
- loading: boolean - Show loading spinner
- loadingMessage: string - Custom loading text
- emptyMessage: string - Text when no data
- emptyState: Snippet - Custom empty state component
- stickyHeader: boolean - Sticky table header on scroll
- striped/hoverable/compact: Visual variants

Pagination - Page navigation

<script>
  import { Pagination } from '@mrintel/villain-ui';
  
  let currentPage = $state(1);
  const totalPages = 10;
</script>

<Pagination bind:currentPage {totalPages} />

Icon Examples:

<script>
  import { Pagination } from '@mrintel/villain-ui';
  import { ChevronLeftIcon, ChevronRightIcon } from 'your-icon-library';
  
  let currentPage = $state(1);
</script>

<!-- Pagination with custom prev/next icons -->
<Pagination 
  {currentPage} 
  totalPages={10}
  onPageChange={(page) => currentPage = page}
>
  {#snippet prevIcon()}
    <ChevronLeftIcon class="w-5 h-5" />
  {/snippet}
  {#snippet nextIcon()}
    <ChevronRightIcon class="w-5 h-5" />
  {/snippet}
</Pagination>

<!-- Icon-only pagination (no "Previous"/"Next" text) -->
<Pagination 
  {currentPage} 
  totalPages={10}
  showLabels={false}
  onPageChange={(page) => currentPage = page}
>
  {#snippet prevIcon()}
    <ChevronLeftIcon class="w-5 h-5" />
  {/snippet}
  {#snippet nextIcon()}
    <ChevronRightIcon class="w-5 h-5" />
  {/snippet}
</Pagination>

Badge - Status badge

<script>
  import { Badge } from '@mrintel/villain-ui';
</script>

<!-- Basic variants -->
<Badge variant="success">Active</Badge>
<Badge variant="warning">Pending</Badge>
<Badge variant="error">Error</Badge>
<Badge variant="accent">Accent</Badge>

<!-- Feature variant - purple accent styling -->
<Badge variant="feature">New Feature</Badge>
<Badge variant="feature">Beta</Badge>

<!-- With hover effects -->
<Badge variant="feature" hover>Hoverable Badge</Badge>

<!-- With persistent glow (can be toggled dynamically for blinking) -->
<Badge variant="accent" glow>Glowing Badge</Badge>

<!-- With icon -->
<Badge variant="accent" size="md" hover>
  {#snippet icon()}
    <svg class="w-3 h-3" fill="currentColor" viewBox="0 0 20 20">
      <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
    </svg>
  {/snippet}
  Verified
</Badge>

Props:

• variant?: 'default' | 'success' | 'warning' | 'error' | 'accent' | 'feature' - Badge style (default: 'default')
• size?: 'sm' | 'md' - Badge size (default: 'md')
• icon?: Snippet - Optional icon content
• hover?: boolean - Enable hover effects (darkened background + glow for accent/feature variants) (default: false)
• glow?: boolean - Apply accent glow effect, can be toggled dynamically for blinking animations (default: false)
• class?: string - Additional CSS classes

Note: The feature variant creates a purple-accented badge perfect for highlighting new features or promotional content. Use hover={true} for interactive badges and glow={true} for persistent or animated glow effects.

Tag - Removable tag

<script>
  import { Tag } from '@mrintel/villain-ui';
</script>

<Tag onRemove={() => console.log('Removed')}>JavaScript</Tag>
<Tag>TypeScript</Tag>

Icon Examples:

<!-- Tag with icon -->
<Tag variant="accent">
  {#snippet icon()}
    <StarIcon class="w-4 h-4" />
  {/snippet}
  Featured
</Tag>

<!-- Dismissible tag with icon -->
<Tag dismissible ondismiss={() => console.log('Removed')}>
  {#snippet icon()}
    <TagIcon class="w-4 h-4" />
  {/snippet}
  JavaScript
</Tag>

<!-- Multiple tags with different icons -->
<div class="flex gap-2">
  <Tag>
    {#snippet icon()}
      <CheckCircleIcon class="w-4 h-4" />
    {/snippet}
    Verified
  </Tag>
  <Tag variant="accent">
    {#snippet icon()}
      <FireIcon class="w-4 h-4" />
    {/snippet}
    Trending
  </Tag>
</div>

List - Styled list

<script>
  import { List } from '@mrintel/villain-ui';
  
  const items = ['Item 1', 'Item 2', 'Item 3'];
</script>

<List {items} variant="ordered" />

Icon Example:

<script>
  import { List } from '@mrintel/villain-ui';
  import { CheckIcon, XIcon, ClockIcon } from 'your-icon-library';
  
  const items = [
    { 
      label: 'Task completed', 
      icon: () => `{@render CheckIcon({ class: 'w-5 h-5 text-success' })}` 
    },
    { 
      label: 'Task pending', 
      icon: () => `{@render ClockIcon({ class: 'w-5 h-5 text-warning' })}` 
    },
    { 
      label: 'Task failed', 
      icon: () => `{@render XIcon({ class: 'w-5 h-5 text-error' })}` 
    }
  ];
</script>

<List {items} variant="unordered" />

<!-- Or with custom rendering -->
<List variant="unordered">
  {#each items as item}
    <li class="flex items-center gap-3">
      {#if item.icon}
        <span class="inline-flex items-center justify-center">
          {@render item.icon()}
        </span>
      {/if}
      {item.label}
    </li>
  {/each}
</List>

Avatar - User avatar

<script>
  import { Avatar } from '@mrintel/villain-ui';
</script>

<Avatar src="/avatar.jpg" alt="User" size="md" />
<Avatar initials="JD" size="lg" />

CodeBlock - Presentational component for displaying syntax-highlighted code

A luxury-styled code display component that provides layout, styling, and optional features like line numbers, filename headers, and line highlighting. Consumers control syntax highlighting by providing pre-highlighted HTML via the default slot.

Key Features:

• Glass morphism aesthetic with custom scrollbars
• Built-in copy button with visual feedback
• Optional line numbers with highlighting support
• Optional filename header display
• Consumers choose their preferred syntax highlighter
• Responsive overflow handling

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | filename | string | undefined | Optional filename to display in the header | | showLineNumbers | boolean | false | Whether to show line numbers in the gutter | | lineCount | number | 0 | Total number of lines (required when showLineNumbers is true) | | highlightLines | number[] | [] | Array of 1-indexed line numbers to highlight in the gutter | | showCopy | boolean | true | Whether to show the copy button | | code | string | undefined | Raw code text for copying (if not provided, extracts from rendered content) |

Important Notes:

• Security Warning: Consumers must sanitize HTML before passing to CodeBlock to prevent XSS attacks. Use trusted syntax highlighters (Shiki, Prism, Highlight.js) and avoid user-generated content without sanitization.
• Apply .line class to each code line and .highlighted class to highlighted lines for consistent styling
• Line numbers are 1-indexed (first line is 1, not 0)
• When using showLineNumbers, provide the lineCount prop for proper rendering

Basic Usage:

<script>
  import { CodeBlock } from '@mrintel/villain-ui';

  const code = `function hello() {
  console.log('Hello, world!');
}`;

  const highlightedCode = `<pre><code class="language-javascript">
<span class="token keyword">function</span> <span class="token function">hello</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'Hello, world!'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre>`;
</script>

<!-- Copy button shown by default, uses raw code text -->
<CodeBlock {code}>
  {@html highlightedCode}
</CodeBlock>

<!-- Hide copy button if needed -->
<CodeBlock showCopy={false}>
  {@html highlightedCode}
</CodeBlock>

With Line Numbers:

<script>
  import { CodeBlock } from '@mrintel/villain-ui';
  
  const code = `function greet(name) {
  return \`Hello, \${name}!\`;
}`;
  
  const lineCount = code.split('\n').length;
  // Assume you have a highlighter that returns HTML
  const highlightedCode = yourHighlighter(code, 'javascript');
</script>

<CodeBlock showLineNumbers {lineCount}>
  {@html highlightedCode}
</CodeBlock>

With Highlighted Lines:

<script>
  import { CodeBlock } from '@mrintel/villain-ui';
  
  const code = `function calculate(a, b) {
  const sum = a + b;
  return sum * 2;
}`;
  
  const lineCount = 4;
  const highlightedCode = yourHighlighter(code, 'javascript');
  const highlightLines = [2]; // Highlight line 2
</script>

<CodeBlock showLineNumbers {lineCount} {highlightLines}>
  {@html highlightedCode}
</CodeBlock>

With Filename:

<script>
  import { CodeBlock } from '@mrintel/villain-ui';
  
  const code = `export function add(a: number, b: number): number {
  return a + b;
}`;
  
  const highlightedCode = yourHighlighter(code, 'typescript');
</script>

<CodeBlock filename="utils.ts">
  {@html highlightedCode}
</CodeBlock>

Integration with Shiki:

<script>
  import { CodeBlock } from '@mrintel/villain-ui';
  import { codeToHtml } from 'shiki';
  import { onMount } from 'svelte';
  
  const code = `function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}`;
  
  let highlightedCode = $state('');
  let lineCount = $state(0);
  
  onMount(async () => {
    highlightedCode = await codeToHtml(code, {
      lang: 'javascript',
      theme: 'github-dark'
    });
    lineCount = code.split('\n').length;
  });
</script>

<CodeBlock filename="fibonacci.js" showLineNumbers {lineCount} highlightLines={[2, 3]}>
  {@html highlightedCode}
</CodeBlock>

Integration with Prism.js:

<script>
  import { CodeBlock } from '@mrintel/villain-ui';
  import Prism from 'prismjs';
  import 'prismjs/themes/prism-tomorrow.css';
  
  const code = `const greeting = (name) => {
  console.log(\`Hello, \${name}!\`);
};`;
  
  const lineCount = code.split('\n').length;
  const highlightedCode = Prism.highlight(code, Prism.languages.javascript, 'javascript');
</script>

<CodeBlock showLineNumbers {lineCount}>
  <pre><code class="language-javascript">{@html highlightedCode}</code></pre>
</CodeBlock>

Integration with Highlight.js:

<script>
  import { CodeBlock } from '@mrintel/villain-ui';
  import hljs from 'highlight.js';
  import 'highlight.js/styles/github-dark.css';
  
  const code = `public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}`;
  
  const lineCount = code.split('\n').length;
  const highlightedCode = hljs.highlight(code, { language: 'java' }).value;
</script>

<CodeBlock filename="HelloWorld.java" showLineNumbers {lineCount}>
  <pre><code class="language-java">{@html highlightedCode}</code></pre>
</CodeBlock>

Stat - Statistic display

<script>
  import { Stat } from '@mrintel/villain-ui';
</script>

<Stat label="Total Users" value="1,234" change="+12.5%" trend="up" />

Sparkline - Lightweight micro trend visualizations

A zero-dependency SVG sparkline component for displaying micro trends in dashboards and data-rich interfaces. Perfect for showing quick visual trends without the overhead of a full charting library.

Key Features:

• Pure SVG rendering (zero dependencies)
• Fully themed with villain-ui CSS variables
• Smooth draw-in animation with reduced motion support
• Optional gradient fills and data point dots
• Tiny bundle size (~2KB)
• Flexible sizing and styling

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | number[] | required | Array of numeric data points to plot | | color | string | var(--color-accent-soft) | Line stroke color (CSS color or variable) | | height | number | 40 | Chart height in pixels | | width | number | 200 | Chart width in pixels | | showDots | boolean | false | Show dots at each data point | | showFill | boolean | false | Show gradient fill below the line | | strokeWidth | number | 2 | Line thickness in pixels | | animationDuration | number | 500 | Animation duration in ms (0 to disable) |

Basic Usage:

<script>
  import { Sparkline } from '@mrintel/villain-ui';

  const weeklyData = [120, 135, 128, 142, 155, 148, 160];
</script>

<Sparkline data={weeklyData} />

With Fill and Dots:

<script>
  import { Sparkline } from '@mrintel/villain-ui';

  const trendData = [10, 15, 12, 18, 22, 19, 25];
</script>

<Sparkline
  data={trendData}
  showFill={true}
  showDots={true}
  height={60}
  color="var(--color-success)"
/>

Integrated with Stat Component (Gym Planner Example):

<script>
  import { Stat, Sparkline } from '@mrintel/villain-ui';

  const volumeTrend = [12500, 13200, 12800, 14100, 15200, 14800, 16000];
</script>

<Stat
  label="7-Day Volume"
  value="16,000 lbs"
  trend="up"
  change={12.5}
  description="gym planner example"
>
  <div style="margin-top: 1rem;">
    <Sparkline
      data={volumeTrend}
      height={40}
      width={180}
      color="var(--color-success)"
      showFill={true}
    />
  </div>
</Stat>

Custom Colors and Sizes:

<script>
  import { Sparkline } from '@mrintel/villain-ui';

  const revenueData = [5400, 5800, 5200, 6100, 6500, 6200, 6800];
  const downtrendData = [180, 175, 165, 158, 150, 145, 138];
</script>

<!-- Success trend (green) -->
<Sparkline data={revenueData} color="var(--color-success)" showFill={true} />

<!-- Error trend (red) -->
<Sparkline data={downtrendData} color="var(--color-error)" />

<!-- Large with thick stroke -->
<Sparkline
  data={revenueData}
  height={80}
  width={400}
  strokeWidth={3}
  color="var(--color-success)"
  showFill={true}
/>

Accessibility:

• Respects prefers-reduced-motion - disables animation when requested
• Includes role="img" and aria-label for screen readers
• Color is not the only indicator of information (use with labels/values)

For Advanced Charting:

Sparkline is designed for simple micro trends. For complex visualization needs (multi-series charts, axes, legends, tooltips, bar/pie/scatter charts), integrate established charting libraries:

• Chart.js - Versatile canvas-based charts
• uPlot - Extremely fast time-series charts
• Apache ECharts - Feature-rich enterprise charts

These libraries integrate easily with villain-ui theming via CSS variables.

CalendarGrid - Interactive monthly calendar with event support

A fully-featured calendar grid component for displaying events, selecting dates, and navigating months. Perfect for scheduling interfaces, date selection, and event dashboards.

Key Features:

• Monthly calendar grid with prev/next month navigation
• Event display with customizable rendering
• Date selection with keyboard navigation
• Configurable week start day (Sunday/Monday)
• Optional week numbers
• Today highlighting
• Custom cell rendering via snippets
• Fully accessible with ARIA attributes

Props:

| Prop | Type | Default | Description | |------|------|---------|-------------| | month | Date | new Date() | Currently displayed month (bindable) | | events | CalendarEvent[] | [] | Array of events to display | | selectedDate | Date | undefined | Currently selected date (bindable) | | onDateSelect | (date: Date) => void | - | Callback when date is clicked | | onMonthChange | (date: Date) => void | - | Callback when month changes | | renderCell | Snippet<[CellData]> | - | Custom cell rendering snippet | | weekStartsOn | 0 \| 1 | 0 | Week start day (0=Sunday, 1=Monday) | | showWeekNumbers | boolean | false | Display week numbers | | highlightToday | boolean | true | Highlight current date | | class | string | '' | Additional CSS classes |

CalendarEvent Interface:

interface CalendarEvent {
  id: string;
  title: string;
  date: Date | string;
  color?: string;
  description?: string;
}

CellData Interface (for renderCell):

interface CellData {
  date: Date;
  events: CalendarEvent[];
  isToday: boolean;
  isSelected: boolean;
  isCurr