README.md

Khangul

Multiplatform Hangul processor library for Kotlin & JS projects, based on reverse-engineered Branah keyboard algorithm. Supported platforms:

• JS (Node, Browser)
• Kotlin (JVM, JS, Native)

Usage

Install khangul npm package:

$ npm i khangul

Import HangulContext:

import { HangulContext } from 'khangul'

Create a new instance of HangulContext and use it to process Hangul:

const hangulContext = new HangulContext()
console.log(hangulContext.getValue()) // ''

khangulContext.appendLetter('ㅇ')
khangulContext.appendLetter('ㅏ')
khangulContext.appendLetter('ㄴ')
console.log(hangulContext.getValue()) // 안

khangulContext.removeLastLetter()
console.log(hangulContext.getValue()) // 아

Utilities

Hangul.consonants
// output: ['ㄱ', 'ㄴ', 'ㄷ', ...]

Hangul.vowels
// output: ['ㅏ', 'ㅑ', 'ㅓ', ...]

Hangul.combinationVowels
// output: ['ㅐ', 'ㅒ', 'ㅔ', ...]

Hangul.tenseConsonants
// output: ['ㄲ', 'ㄸ', 'ㅃ', ...]

Hangul.getAll()
// output [ ...consonants, ...tenseConsonants, ...vowels, ...combinationVowels ]

Hangul.generateRandomSyllable()
// example output: 벼, 으, 뷰, 티, 이, 포, 쥬, 슜, 우 

Use-cases

The library handles natural Hangul input, so its main use-case is to be used in text editors, chat apps, etc. As an example, there's a preview of react-simple-keyboard component integrated with our Hangul context & compatibile keyboard layout:

import { HangulContext } from "khangul"
import Keyboard from 'react-simple-keyboard'

const hangulContext = useRef(new HangulContext())
const keyboard = useRef(null as unknown as SimpleKeyboard)
const [userInput, setUserInput] = useState('')
const [layoutName, setLayoutName] = useState('default')

const onKeyPress = (button: string) => {
    if (button === "{shift}" || button === "{lock}") {
        setLayoutName(layoutName === "default" ? "shift" : "default")
        return
    }
    else if (button === "{bksp}") {
        hangulContext.current.removeLastLetter()
        setUserInput(hangulContext.current.getValue())
        return
    }
    hangulContext.current.appendLetter(button)
    setUserInput(hangulContext.current.getValue())
}

return (
    <>
        <Input
            placeholder='Type here...'
            value={userInput}
            onChange={() => {}}
        />
        <Keyboard
            keyboardRef={ref => (keyboard.current = ref)}
            enableLayoutCandidates={false}
            layoutName={layoutName}
            onChange={() => {}}
            onKeyPress={onKeyPress}
            layout={{
                default: [
                    "` 1 2 3 4 5 6 7 8 9 0 - = {bksp}",
                    "{tab} ㅂ ㅈ ㄷ ㄱ ㅅ ㅛ ㅕ ㅑ ㅐ ㅔ [ ] \\",
                    "{lock} ㅁ ㄴ ㅇ ㄹ ㅎ ㅗ ㅓ ㅏ ㅣ ; ' {enter}",
                    "{shift} ㅋ ㅌ ㅊ ㅍ ㅠ ㅜ ㅡ , . / {shift}",
                    ".com @ {space}",
                ],
                    shift: [
                    "~ ! @ # $ % ^ & * ( ) _ + {bksp}",
                    "{tab} ㅃ ㅉ ㄸ ㄲ ㅆ    ㅒ ㅖ { } |",
                    '{lock}         : " {enter}',
                    "{shift} |       < > ? {shift}",
                    ".com @ {space}",
                ],
            }}
        />
    </>
)