HelaUI — @mccustomapps/helaui

Sri Lankan-flavoured UI component library with Sinhala font support, traditional Sinhala calendar, Star Rating system, modern Studio AI Chatbox, Snackbar feedback, QR Code & Barcode generators, tropical rain background, and the iconic Ira Handa sun mandala (ඉර හඳ / සූර්ය මණ්ඩලය).

Table of Contents

• Installation
• Quick Start
• Components
  • Rating (Star Rating)
  • Chatbox (Studio AI Chat)
  • Snackbar
  • Calendar (Sinhala Months & BE)
  • QRCode
  • Barcode
  • TextField
  • Button
  • SunMandala (Ira Handa)
  • DestinationCard
  • RainBackground
• Theming
• i18n / Localisation
• CSS Imports
• TypeScript
• License

Installation

npm install @mccustomapps/helaui

Quick Start

// Import design tokens and fonts
import '@mccustomapps/helaui/theme.css';
import '@mccustomapps/helaui/sinhala.css';

// Import CSS for the components you use
import '@mccustomapps/helaui/rating.css';
import '@mccustomapps/helaui/chatbox.css';
import '@mccustomapps/helaui/calendar.css';
import '@mccustomapps/helaui/snackbar.css';
import '@mccustomapps/helaui/textfield.css';

// Import component classes
import { Rating, Chatbox, Calendar, Snackbar } from '@mccustomapps/helaui';

// Mount Star Rating
const rating = new Rating({ value: 4, color: '#FFBE00' });
document.body.appendChild(rating.element);

// Mount Studio AI Chatbox
const chatbox = new Chatbox({ mode: 'embedded' });
document.body.appendChild(chatbox.element);

Components

Rating (Star Rating)

A 5-star rating system built from scratch with smooth hover-and-fill effects, customizable fill & stroke colors, adjustable border thickness, predefined read-only mode, precision fractional values (e.g. 3.5 stars), and accessible keyboard controls.

import { Rating } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/rating.css';

const rating = new Rating({
  value: 4,               // initial rating (0-5, integers or fractions)
  max: 5,                 // total stars
  color: '#FFBE00',       // filled/hovered star color
  strokeColor: '#000000', // outline border color
  strokeWidth: 1.0,       // outline border thickness
  size: '32px',           // star size
  gap: '8px',             // gap between stars
  readOnly: false,        // interactive or read-only
  onChange: (value) => {
    console.log('Selected rating:', value);
  },
  onHover: (hoveredValue) => {
    console.log('Hovering:', hoveredValue);
  },
});

document.getElementById('container').appendChild(rating.element);

Options — RatingOptions

| Option | Type | Default | Description | |---|---|---|---| | value | number | 0 | Initial rating value (integers or fractions) | | max | number | 5 | Total number of stars | | readOnly | boolean | false | Read-only mode (disables clicks and hovers) | | disabled | boolean | false | Disabled state with muted opacity | | color | string | '#FFBE00' | Fill color for active and hovered stars | | unfilledColor | string | 'transparent' | Background color inside unfilled stars | | strokeColor | string | '#000000' | Outline border color | | strokeWidth | number | 1.0 | Outline border thickness in SVG units | | size | string \| number | '32px' | Star width and height | | gap | string \| number | '8px' | Spacing between stars | | clearable | boolean | true | Clicking the current rating resets it to 0 | | itemLabels | string[] | — | Accessible labels / tooltips per star | | name | string | — | Form field name (creates hidden input) | | onChange | (value: number) => void | — | Value change callback | | onHover | (value: number \| null) => void | — | Hover state change callback |

Methods

rating.getValue();              // → number
rating.setValue(4.5);           // updates rating programmatically
rating.setReadOnly(true);       // toggles read-only mode
rating.setDisabled(true);       // toggles disabled state
rating.setColor('#8D153A');     // updates fill color
rating.setStrokeColor('#000');  // updates border stroke color
rating.setStrokeWidth(1.2);     // updates border thickness
rating.setSize('36px');         // resizes stars
rating.reset();                 // resets rating to 0
rating.destroy();               // removes from DOM and cleans up

Chatbox (Studio AI Chat)

A modern conversational AI assistant widget featuring multi-user session switching with assignable letters/initials (A, H, S, C), assistant quotes, quick suggestion chips, animated typing indicators, and a floating minimized launcher pill that dynamically reflects the active assistant.

import { Chatbox } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/chatbox.css';

const chatbox = new Chatbox({
  users: [
    {
      id: 'atlas',
      name: 'Atlas AI',
      subtitle: 'Creative Studio Assistant',
      letter: 'A',
      color: '#4F46E5',
      online: true,
      messages: [
        {
          id: '1',
          sender: 'bot',
          text: "Hello! I've prepped your workspace for the **Brand Refresh**.",
          suggestions: ['Write Headlines', 'Audit Assets'],
        },
      ],
    },
    {
      id: 'hela',
      name: 'Hela Guide',
      subtitle: 'Sinhala & Cultural Assistant',
      letter: 'H',
      color: '#8D153A',
      online: true,
      messages: [
        {
          id: '1',
          sender: 'bot',
          text: 'ආයුබෝවන්! ශ්‍රී ලාංකේය සංස්කෘතික සහායක වෙත සාදරයෙන් පිළිගනිමු.',
          quote: '"සෑම පියවරකදීම නව නිර්මාණශීලී අත්දැකීමක්."',
        },
      ],
    },
  ],
  mode: 'embedded', // 'embedded' | 'floating'
  onSend: (message, activeUser, instance) => {
    // Handle message sending & bot response
    instance.showTyping(true);
    setTimeout(() => {
      instance.showTyping(false);
      instance.addMessage({
        sender: 'bot',
        text: `Processed "${message}" successfully.`,
      });
    }, 1000);
  },
});

document.getElementById('container').appendChild(chatbox.element);

Options — ChatboxOptions

| Option | Type | Default | Description | |---|---|---|---| | users | ChatUser[] | built-in profiles | List of assistant profiles with letter avatars & histories | | activeUserId | string | first user | Initially active user profile ID | | mode | 'embedded' \| 'floating' | 'embedded' | Render mode (inline card or floating bottom widget) | | position | 'bottom-right' \| 'bottom-left' | 'bottom-right' | Position when in floating mode | | defaultOpen | boolean | true | Initial open state | | placeholder | string | 'Type a message...' | Input placeholder | | footerText | string | 'Powered by Atlas Studio' | Subtitle footer branding | | primaryColor | string | '#4F46E5' | Default accent color | | width / height | string | '380px' / '580px' | Container dimensions | | onSend | (msg, user, chatbox) => void | — | Sent message callback | | onSuggestionClick| (suggestion, user, chatbox) => void | — | Quick suggestion chip click handler | | onUserChange | (user, index, chatbox) => void | — | Session / assistant switch handler |

Methods

chatbox.addMessage({ sender: 'bot', text: 'Hello!', quote: '"Great idea."' });
chatbox.showTyping(true);       // shows 3-dot typing indicator
chatbox.setActiveUser('hela');  // switches active user profile
chatbox.getActiveUser();        // → active ChatUser object
chatbox.minimize();             // collapses to minimized launcher pill
chatbox.open();                 // expands chat window
chatbox.toggle();               // toggles open / minimized state
chatbox.clearMessages();        // clears current user conversation
chatbox.destroy();

Snackbar

Non-blocking toast notification system matching HelaUI design tokens with accessible live regions and action triggers.

import { Snackbar } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/snackbar.css';

// Show a notification
Snackbar.show({
  message: 'Changes saved successfully',
  variant: 'success', // 'default' | 'success' | 'error' | 'warning' | 'info'
  duration: 4000,
  position: 'bottom-center',
  actionLabel: 'Undo',
  onAction: () => {
    console.log('Undo clicked');
  },
});

Calendar

A from-scratch Sinhala calendar featuring the 12 traditional Sinhala months (දුරුතු to උඳුඅප්), Buddhist Era (බුද්ධ වර්ෂ) year calculation, and Poya day markers.

import { Calendar, formatSinhalaNumeral, SINHALA_MONTH_NAMES } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/calendar.css';

const calendar = new Calendar({
  value: new Date(),
  showBuddhistEra: true,
  highlightToday: true,
  onSelect: (date, sinhalaFormatted) => {
    console.log(sinhalaFormatted); // e.g. "2026 වෙසක් 15"
  },
});

document.getElementById('container').appendChild(calendar.element);

Sinhala Month Names Reference: දුරුතු (Duruthu), නවම් (Navam), මැදින් (Medin), බක් (Bak), වෙසක් (Vesak), පොසොන් (Poson), ඇසළ (Esala), නිකිණි (Nikini), බිනර (Binara), වප් (Vap), ඉල් (Il), උඳුඅප් (Unduvap).

QRCode

Built-from-scratch QR Code generator (Model 2, v1–v10, EC L/M/Q/H) rendering crisp SVG/Canvas barcodes without external dependencies.

import { QRCode } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/qrcode.css';

const qr = new QRCode({
  value: 'https://helaui.dev',
  size: 256,
  errorCorrection: 'M',
  foreground: '#000000',
  background: '#ffffff',
});

document.getElementById('container').appendChild(qr.element);

Barcode

Pure Code 128 barcode generator rendering scalable SVG barcodes without third-party dependencies.

import { Barcode } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/barcode.css';

const barcode = new Barcode({
  value: 'HELAUI-2026',
  width: 600,
  height: 140,
});

document.getElementById('container').appendChild(barcode.element);

TextField

A locale-aware text input with built-in Sinhala font support and automatic translation variant handling.

import { TextField } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/textfield.css';

const field = new TextField({
  variant: 'name',       // 'name' | 'password' | 'email' | 'disabled'
  type: 'text',
  label: 'Your Name',
  placeholder: 'Enter your name',
  sinhala: true,
});

document.getElementById('container').appendChild(field.element);

Button

Pill action buttons: filled terracotta primary action and teal outline secondary action.

import { Button } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/button.css';

const btn = new Button({
  variant: 'primary',
  label: 'Book Your Trip',
  onClick: () => console.log('Clicked!'),
});

document.getElementById('container').appendChild(btn.element);

SunMandala

The traditional Sri Lankan Ira Handa (ඉර හඳ) sun face mandala. The central face remains stationary and upright while the surrounding aura (rays, lotus rings, and sacred motifs) rotates continuously.

import { SunMandala } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/sun-mandala.css';

const mandala = new SunMandala({
  size: '300px',
  duration: 30,       // seconds per full rotation cycle
  faceRadius: '22%',  // radius of stationary center face
});

document.getElementById('container').appendChild(mandala.element);

DestinationCard

Decorative parchment card shell featuring cream background, teal/gold frame, side Sinhala script, and a peacock/lotus footer.

import { DestinationCard } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/destination-card.css';

const card = new DestinationCard({ height: '280px' });
document.getElementById('container').appendChild(card.element);

RainBackground

Animated tropical rain background with falling food/leaf sprites (Kokis, Fritter, Swirl, Leaf).

import { RainBackground } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/rain-background.css';

const rain = new RainBackground({ density: 20 });

React / Next.js Client Component:

'use client';

import { useEffect } from 'react';
import { RainBackground } from '@mccustomapps/helaui';
import '@mccustomapps/helaui/rain-background.css';

export function HelaRain() {
  useEffect(() => {
    const rain = new RainBackground({ density: 16 });
    return () => rain.destroy();
  }, []);

  return null;
}

Theming

HelaUI uses CSS custom properties for all design tokens.

import '@mccustomapps/helaui/theme.css';
import { applyTheme, resetTheme, defaultTheme } from '@mccustomapps/helaui';

// Apply a custom palette
applyTheme({
  primary:   '#8D153A',
  secondary: '#FFBE00',
  success:   '#005B33',
  accent:    '#FF7A00',
  black:     '#000000',
  white:     '#FFFFFF',
  grey:      '#808080',
}, document.documentElement);

// Reset back to defaults
resetTheme(document.documentElement);

i18n / Localisation

Built-in English (en) and Sinhala (si) support with live subscription reactivity.

import { setLocale, getLocale, t, subscribeLocaleChange } from '@mccustomapps/helaui';

// Switch language to Sinhala
setLocale('si');

// Translate key
t('textField.name.label'); // → 'නම'

// Subscribe to locale changes
const unsubscribe = subscribeLocaleChange(() => {
  console.log('Locale updated:', getLocale());
});

CSS Imports

Import CSS individually as needed:

import '@mccustomapps/helaui/theme.css';            // Design tokens
import '@mccustomapps/helaui/sinhala.css';          // Sinhala font face
import '@mccustomapps/helaui/rating.css';           // Rating styles
import '@mccustomapps/helaui/chatbox.css';          // Chatbox styles
import '@mccustomapps/helaui/calendar.css';         // Calendar styles
import '@mccustomapps/helaui/snackbar.css';         // Snackbar styles
import '@mccustomapps/helaui/qrcode.css';           // QRCode styles
import '@mccustomapps/helaui/barcode.css';          // Barcode styles
import '@mccustomapps/helaui/textfield.css';        // TextField styles
import '@mccustomapps/helaui/button.css';           // Button styles
import '@mccustomapps/helaui/sun-mandala.css';      // SunMandala styles
import '@mccustomapps/helaui/destination-card.css'; // DestinationCard styles
import '@mccustomapps/helaui/rain-background.css';  // RainBackground styles

TypeScript

Full TypeScript type definitions are bundled with the library.

import type {
  RatingOptions,
  ChatboxOptions,
  ChatUser,
  ChatMessage,
  CalendarOptions,
  SnackbarOptions,
  QRCodeOptions,
  TextFieldOptions,
  ButtonOptions,
  SunMandalaOptions,
  DestinationCardOptions,
  RainBackgroundOptions,
  HelaTheme,
  HelaLocale,
} from '@mccustomapps/helaui';

License

MIT © mccustomapps