@mccustomapps/helaui 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,339 @@
+# HelaUI — `@mccustomapps/helaui`
+
+> Sri Lankan-flavoured UI component library with **Sinhala font** support, a traditional **Sinhala calendar**, a **rain background** effect, and the iconic **Ira Handa sun mandala** (ඉර හඳ / සූර්ය මණ්ඩලය).
+
+[![npm version](https://img.shields.io/npm/v/@mccustomapps/helaui)](https://www.npmjs.com/package/@mccustomapps/helaui)
+[![license](https://img.shields.io/npm/l/@mccustomapps/helaui)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/@mccustomapps/helaui)](https://www.npmjs.com/package/@mccustomapps/helaui)
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Components](#components)
+  - [TextField](#textfield)
+  - [Calendar](#calendar)
+  - [SunMandala](#sunmandala)
+  - [RainBackground](#rainbackground)
+- [Theming](#theming)
+- [i18n / Localisation](#i18n--localisation)
+- [CSS Imports](#css-imports)
+- [TypeScript](#typescript)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @mccustomapps/helaui
+```
+
+---
+
+## Quick Start
+
+```js
+// Import the CSS for the components you use
+import '@mccustomapps/helaui/textfield.css';
+import '@mccustomapps/helaui/calendar.css';
+import '@mccustomapps/helaui/sun-mandala.css';
+import '@mccustomapps/helaui/rain-background.css';
+import '@mccustomapps/helaui/sinhala.css';   // Sinhala font face
+import '@mccustomapps/helaui/theme.css';      // CSS custom-property tokens
+
+// Import components
+import { TextField, Calendar, SunMandala, RainBackground } from '@mccustomapps/helaui';
+
+// Mount components
+const field = new TextField({ variant: 'name' });
+document.body.appendChild(field.element);
+```
+
+---
+
+## Components
+
+### TextField
+
+A locale-aware text input with built-in Sinhala font support.
+
+```js
+import { TextField } from '@mccustomapps/helaui';
+import '@mccustomapps/helaui/textfield.css';
+
+const field = new TextField({
+  variant: 'name',       // 'name' | 'password' | 'email' | 'disabled'
+  type: 'text',          // 'text' | 'password' | 'email'
+  label: 'Your Name',   // explicit label (overrides variant)
+  placeholder: 'Enter name',
+  value: '',
+  sinhala: true,         // force Sinhala font
+});
+
+document.getElementById('container').appendChild(field.element);
+```
+
+**Options — `TextFieldOptions`**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `TextFieldVariant` | — | Resolves label & placeholder from locale |
+| `label` | `string` | — | Explicit label text |
+| `placeholder` | `string` | — | Explicit placeholder text |
+| `type` | `'text' \| 'password' \| 'email'` | `'text'` | Input type |
+| `value` | `string` | — | Initial value |
+| `id` | `string` | auto | HTML id attribute |
+| `sinhala` | `boolean` | auto | Force Sinhala font class |
+| `labelKey` | `string` | — | i18n dot-path for label |
+| `placeholderKey` | `string` | — | i18n dot-path for placeholder |
+
+**Methods**
+
+```js
+field.getValue()               // → string
+field.setValue('hello')
+field.setLabel('Name / නම')
+field.setPlaceholder('Type here…')
+field.setDisabled(true)
+field.setSinhala(true)
+field.focus()
+field.destroy()                // removes locale subscription
+```
+
+---
+
+### Calendar
+
+A from-scratch **Sinhala calendar** with Buddhist Era (බුද්ධ වර්ෂ) and Poya day support.
+
+```js
+import { Calendar } from '@mccustomapps/helaui';
+import '@mccustomapps/helaui/calendar.css';
+
+const calendar = new Calendar({
+  value: new Date(),
+  showBuddhistEra: true,
+  onSelect: (date, sinhalaFormatted) => {
+    console.log(sinhalaFormatted); // e.g. "2567 දුරුතු 15"
+  },
+});
+
+document.getElementById('container').appendChild(calendar.element);
+```
+
+**Options — `CalendarOptions`**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `value` | `Date` | today | Initially selected date |
+| `showBuddhistEra` | `boolean` | `false` | Prefix year with Buddhist Era |
+| `onSelect` | `(date: Date, formatted: string) => void` | — | Selection callback |
+
+**Methods**
+
+```js
+calendar.setShowBuddhistEra(true)
+calendar.getValue()   // → Date | null
+calendar.destroy()
+```
+
+**Helpers**
+
+```js
+import { formatSinhalaNumeral, SINHALA_MONTH_NAMES } from '@mccustomapps/helaui';
+
+formatSinhalaNumeral(2025);   // → 'ෲ෦ෲ෥'
+SINHALA_MONTH_NAMES;          // ['දුරුතු', 'නවම්', …]
+```
+
+---
+
+### SunMandala
+
+The traditional Sri Lankan **Ira Handa** (ඉර හඳ) sun face mandala. The central face stays **stationary** while the surrounding **aura** (rays, lotus rings, and sacred motifs) rotates continuously.
+
+```js
+import { SunMandala } from '@mccustomapps/helaui';
+import '@mccustomapps/helaui/sun-mandala.css';
+
+const mandala = new SunMandala({
+  size: '320px',      // width & height — any CSS length
+  duration: 30,       // rotation cycle in seconds (lower = faster)
+  faceRadius: '22%',  // clip radius of the stationary face overlay
+  paused: false,      // start paused?
+});
+
+document.getElementById('container').appendChild(mandala.element);
+```
+
+**Options — `SunMandalaOptions`**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | built-in | Custom image URL |
+| `alt` | `string` | `'Sri Lankan Ira Handa sun mandala'` | ARIA label |
+| `size` | `string` | `'280px'` | Width & height (any CSS unit) |
+| `duration` | `number` | `36` | Full rotation time in seconds |
+| `faceRadius` | `string` | `'22%'` | Clip radius of the static face overlay |
+| `paused` | `boolean` | `false` | Start with rotation paused |
+
+**Methods**
+
+```js
+mandala.setPaused(true)         // pause / resume
+mandala.isPaused()              // → boolean
+mandala.setDuration(10)         // change speed (seconds per full rotation)
+mandala.setSize('400px')        // resize
+mandala.setFaceRadius('20%')    // adjust face clip radius
+mandala.destroy()               // remove from DOM
+```
+
+**Use your own image**
+
+```js
+import { SunMandala, BUILTIN_SUN_MANDALA_IMAGE } from '@mccustomapps/helaui';
+
+// Built-in Ira Handa artwork
+const mandala = new SunMandala({ src: BUILTIN_SUN_MANDALA_IMAGE });
+
+// Or bring your own circular mandala image
+const mandala = new SunMandala({ src: '/my-mandala.png' });
+```
+
+---
+
+### RainBackground
+
+An animated **tropical rain** background with randomly falling rain streaks over a looping food-photography image.
+
+```js
+import { RainBackground } from '@mccustomapps/helaui';
+import '@mccustomapps/helaui/rain-background.css';
+
+const rain = new RainBackground();
+document.body.insertBefore(rain.element, document.body.firstChild);
+```
+
+**Options — `RainBackgroundOptions`**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `images` | `string[]` | built-in set | Background image URLs |
+| `interval` | `number` | `5000` | Image crossfade interval (ms) |
+
+**Helpers**
+
+```js
+import {
+  BUILTIN_RAIN_IMAGES,
+  DEFAULT_RAIN_IMAGES,
+  getDefaultRainImageUrls,
+} from '@mccustomapps/helaui';
+```
+
+---
+
+## Theming
+
+HelaUI uses **CSS custom properties** for its design tokens.
+
+```js
+import '@mccustomapps/helaui/theme.css';
+import { applyTheme, resetTheme, defaultTheme } from '@mccustomapps/helaui';
+
+// Apply a custom palette to a container (or document.body)
+applyTheme({
+  primary:   '#8d153a',
+  secondary: '#f5a623',
+  success:   '#27ae60',
+  accent:    '#e74c3c',
+  black:     '#111111',
+  white:     '#ffffff',
+  grey:      '#888888',
+}, document.getElementById('app'));
+
+// Reset to defaults
+resetTheme(document.getElementById('app'));
+```
+
+**`HelaTheme` keys:** `primary` · `secondary` · `success` · `accent` · `black` · `white` · `grey`
+
+---
+
+## i18n / Localisation
+
+HelaUI ships with **English** (`en`) and **Sinhala** (`si`) built-in.
+
+```js
+import {
+  applyTranslations,
+  setLocale,
+  getLocale,
+  subscribeLocaleChange,
+  t,
+} from '@mccustomapps/helaui';
+
+// Switch locale
+setLocale('si');
+
+// Translate a key
+t('textField.name.label');   // → 'නම'
+
+// Override / extend translations
+applyTranslations({
+  locale: 'en',
+  overrides: {
+    en: {
+      textField: { name: { label: 'Full Name', placeholder: 'Enter full name' } },
+    },
+  },
+});
+
+// React to locale changes
+const unsub = subscribeLocaleChange(() => {
+  console.log('Locale changed to', getLocale());
+});
+unsub(); // unsubscribe
+```
+
+---
+
+## CSS Imports
+
+Import only what you need:
+
+```js
+import '@mccustomapps/helaui/theme.css';          // design tokens (required)
+import '@mccustomapps/helaui/sinhala.css';         // Sinhala font face
+import '@mccustomapps/helaui/textfield.css';       // TextField styles
+import '@mccustomapps/helaui/calendar.css';        // Calendar styles
+import '@mccustomapps/helaui/sun-mandala.css';     // SunMandala styles
+import '@mccustomapps/helaui/rain-background.css'; // RainBackground styles
+```
+
+---
+
+## TypeScript
+
+Full TypeScript definitions are included. No `@types/` package needed.
+
+```ts
+import type {
+  TextFieldOptions,
+  CalendarOptions,
+  SunMandalaOptions,
+  RainBackgroundOptions,
+  HelaTheme,
+  HelaThemeKey,
+  HelaLocale,
+} from '@mccustomapps/helaui';
+```
+
+---
+
+## License
+
+MIT © [mccustomapps](https://github.com/mccustomapps)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccustomapps/helaui",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "HelaUI components with Sinhala font support",
   "author": "mccustomapps",
   "license": "MIT",
@@ -49,4 +49,4 @@
     "typescript": "^5.8.2",
     "vite": "^6.2.0"
   }
-}
+}