@nuralyui/common

Common UI components package for Nuraly UI Library. This package contains basic building blocks that are commonly used across the component library and in applications.

🧩 Shared Utilities (what this package provides)

Mixins

Base mixins that provide common functionality to all Nuraly UI components:

• NuralyUIBaseMixin / BaseMixin: Combined mixin with theme, dependency, and event handling
• ThemeAwareMixin: Theme management and observation
• DependencyValidationMixin: Component dependency validation
• EventHandlerMixin: Enhanced event handling capabilities

Controllers

Reactive controllers for component behavior:

• ThemeController: Theme observation and management
• SharedDropdownController: Dropdown positioning and behavior

Theme Utilities

• Theme detection and management
• Theme variant types and utilities
• getCurrentTheme, theme constants

Utility Functions

• throttle, debounce, rafThrottle
• Performance optimization helpers

Note: As of 0.1.x, @nuralyui/common no longer re-exports UI components (icon, badge, divider, label). Those should be consumed from their own packages or via the grouped packages like @nuralyui/forms or @nuralyui/layout.

🚀 Installation

npm install @nuralyui/common

Or using yarn:

yarn add @nuralyui/common

📖 Usage

Import Shared Utilities

// Import mixins for creating custom components
import { NuralyUIBaseMixin, ThemeAwareMixin } from '@nuralyui/common/mixins';

// Import controllers
import { ThemeController, SharedDropdownController } from '@nuralyui/common/controllers';

// Import theme utilities
import { getCurrentTheme, type ThemeVariant } from '@nuralyui/common/themes';

// Import utility functions
import { throttle, debounce, rafThrottle } from '@nuralyui/common/utils';

Creating Custom Components with Mixins

import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';
import { NuralyUIBaseMixin } from '@nuralyui/common/mixins';

@customElement('my-component')
export class MyComponent extends NuralyUIBaseMixin(LitElement) {
  render() {
    return html`
      <div data-theme="${this.currentTheme}">
        My themed component
      </div>
    `;
  }
}

Using Controllers

import { LitElement, html } from 'lit';
import { ThemeController } from '@nuralyui/common/controllers';

export class MyComponent extends LitElement {
  private themeController = new ThemeController(this);

  render() {
    return html`
      <div class="${this.themeController.isDark ? 'dark' : 'light'}">
        Theme: ${this.themeController.currentTheme}
      </div>
    `;
  }
}

HTML Usage (utilities only)

Utilities don’t render by themselves. Use them inside your own components or with the grouped/component packages.

🎯 Why Use @nuralyui/common?

Guidance

• Install components from their own packages (e.g., @nuralyui/icon) or grouped packages (@nuralyui/forms, @nuralyui/layout).
• Use @nuralyui/common for mixins, controllers, themes, and utilities.

📚 Component Documentation

For component docs, see the individual packages or grouped packages:

• Icon
• Badge
• Divider
• Label

🔗 Related Packages

• @nuralyui/themes - Theme packages for Nuraly UI
• Individual component packages available on npm under @nuralyui/*

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

BSD-3-Clause © Laabidi Aymen

🔗 Links

• GitHub Repository
• Documentation
• NPM Organization
• Report Issues