dhivehi-input

Dhivehi Input

A modern, lightweight JavaScript library for enabling Dhivehi/Thaana text input in web applications. Automatically converts English keyboard input to Dhivehi characters in real-time.

✨ Features

• 🚀 Easy to use: Just add dhivehi-input class to any input element
• ⌨️ Multiple keyboard layouts: Phonetic, Phonetic Hassan Hameed, Typewriter
• 🔧 Vue.js integration: Composable and directive support
• 📦 Standalone: Works without frameworks
• 🔄 Automatic RTL: Sets right-to-left direction automatically
• 👀 Dynamic detection: Automatically detects new elements added to DOM
• 🎯 Modern ES6+: Clean, maintainable code
• 📱 Zero dependencies: Pure JavaScript implementation
• 💡 TypeScript support: Full type definitions included

📦 Installation

npm install dhivehi-input

Or with yarn:

yarn add dhivehi-input

Or use via CDN:

<script src="https://unpkg.com/dhivehi-input/lib/standalone.umd.min.js"></script>

🚀 Quick Start

Method 1: Simple Class-Based Usage (Recommended)

The simplest way to add Dhivehi input to any element:

<input type="text" class="dhivehi-input" placeholder="ލިޔުއްވާ">

That's it! The input will automatically convert English typing to Dhivehi characters.

Method 2: Custom Keyboard Layout

<input type="text" class="dhivehi-input" data-dhivehi-keyboard="phonetic-hh">
<input type="text" class="dhivehi-input" data-dhivehi-keyboard="typewriter">

Method 3: Programmatic Usage

import DhivehiInput from 'dhivehi-input';

// Create instance
const dhivehi = new DhivehiInput({
    keyboard: 'phonetic',
    className: 'my-dhivehi-input'
});

// Setup specific element
dhivehi.setupElement(document.getElementById('my-input'));

🔧 Vue.js Integration

Plugin Installation

import { createApp } from 'vue';
import DhivehiInputPlugin from 'dhivehi-input/vue';

const app = createApp({});
app.use(DhivehiInputPlugin);

Using the Directive

<template>
  <!-- Simple usage -->
  <input v-dhivehi-input type="text">
  
  <!-- With custom keyboard -->
  <input v-dhivehi-input="'phonetic-hh'" type="text">
  
  <!-- With options -->
  <input v-dhivehi-input="{ keyboard: 'typewriter', enabled: true }" type="text">
</template>

Using the Composable

<script setup>
import { useDhivehiInput } from 'dhivehi-input/vue';

const { translateChar, setupElement, keyboards } = useDhivehiInput();

// Translate individual characters
const dhivehiChar = translateChar('a'); // Returns 'އ'

// Get available keyboards
console.log(Object.keys(keyboards.value)); // ['phonetic', 'phonetic-hh', 'typewriter']
</script>

⌨️ Keyboard Layouts

Phonetic (Default)

• ID: phonetic
• Description: Most popular layout, maps English letters to similar sounding Dhivehi letters
• Example: a → އ, s → ސ, d → ދ

Phonetic Hassan Hameed

• ID: phonetic-hh
• Description: Alternative phonetic layout with different mappings for certain characters
• Example: Similar to phonetic but with variations for alifu, sukun, etc.

Typewriter

• ID: typewriter
• Description: Traditional typewriter layout used in government offices
• Example: Based on physical Dhivehi typewriter key positions

📖 API Reference

Core Functions

import { translateChar, insertTextAtCursor, DhivehiInput } from 'dhivehi-input';

// Translate single character
const translated = translateChar('a', 'phonetic'); // 'އ'

// Insert text at cursor
insertTextAtCursor(inputElement, 'ޖޮއްލާ');

// Create instance
const dhivehi = new DhivehiInput(options);

Configuration Options

const config = {
    keyboard: 'phonetic',           // Default keyboard layout
    className: 'dhivehi-input',     // CSS class to detect
    activeClassName: 'dhivehi-input-active', // Applied to active elements
    enableRtl: true,                // Enable RTL styling
    autoInit: true                  // Auto-initialize on creation
};

Instance Methods

const dhivehi = new DhivehiInput();

// Setup/remove elements
dhivehi.setupElement(element);
dhivehi.removeElement(element);

// Control observation
dhivehi.startObserver();
dhivehi.stopObserver();

// Keyboard management
dhivehi.setKeyboard(element, 'phonetic-hh');
dhivehi.getKeyboards(); // ['phonetic', 'phonetic-hh', 'typewriter']

// Cleanup
dhivehi.destroy();

🎨 Styling

The library automatically applies appropriate RTL styling. You can customize the appearance:

.dhivehi-input {
    font-family: 'MV Boli', 'Faruma', Thaana, Arabic, sans-serif;
    direction: rtl;
    text-align: right;
}

.dhivehi-input-active:focus {
    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
    border-color: #3b82f6;
}

🌐 Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• IE 11+ (with polyfills)

📱 Supported Elements

Works with:

• <input type="text">
• <input type="search">
• <input type="url">
• <input type="tel">
• <input type="password">
• <textarea>
• Any element with contenteditable="true"

🔍 Advanced Usage

Multiple Instances

// Different configurations for different sections
const adminDhivehi = new DhivehiInput({
    className: 'admin-dhivehi',
    keyboard: 'typewriter'
});

const userDhivehi = new DhivehiInput({
    className: 'user-dhivehi', 
    keyboard: 'phonetic'
});

Custom Event Handling

// Listen for Dhivehi input events
document.addEventListener('dhivehi:input', (event) => {
    console.log(`Typed: ${event.detail.originalChar} → ${event.detail.translatedChar}`);
});

// Listen for setup events
document.addEventListener('dhivehi:setup', (event) => {
    console.log(`Element setup with keyboard: ${event.detail.keyboard}`);
});

Dynamic Keyboard Switching

const dhivehi = new DhivehiInput();

// Switch keyboard for specific element
dhivehi.setKeyboard(inputElement, 'phonetic-hh');

// Or via data attribute
inputElement.dataset.dhivehiKeyboard = 'typewriter';

🛠️ Development

# Clone the repository
git clone https://github.com/yourusername/dhivehi-input.git
cd dhivehi-input

# Install dependencies
npm install

# Build the library
npm run build

# Build and watch for changes
npm run dev

# Format code
npm run format

# Lint code
npm run lint

📄 Examples

Check out the examples/ directory for complete implementation examples:

• Basic HTML usage
• Vue.js integration
• React integration (coming soon)
• Advanced customization

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the original JTK (Javascript Thaana Keyboard) by Jawish Hameed
• Thanks to the Maldivian developer community for feedback and testing

📞 Support

If you have any questions or need help integrating this library, please:

• Check the documentation
• Search existing issues
• Create a new issue

Made with ❤️ for the Maldivian developer community