hangul-unicode-composer 1.6.0

package/README.md

@@ -0,0 +1,101 @@
+# hangul-unicode-composer
+
+> Modern TypeScript port of HUC (Hangul Unicode Composer). A lightweight, zero-dependency library to compose Korean Jamo characters into Unicode Hangul syllables in the browser and Node.js.
+
+## Installation
+
+```bash
+npm install hangul-unicode-composer
+```
+
+## Features
+* **Zero Dependencies**: Pure TypeScript/ESM module.
+* **Standard Unicode Compliant**: Implements standard Hangul Syllable Composition rules (`0xAC00`).
+* **Carry-over Composition**: Intuitively handles splitting complex consonants when new vowels are typed (e.g. `인` + `아` -> `이` + `나`).
+* **Session Archives**: Save and restore typing buffers easily for multiple inputs.
+* **Event & Callback hooks**: Simple native `EventTarget` listeners or direct callback functions (`onUpdate`, `onLimited`, `onError`).
+
+## Usage
+
+### 1. Basic Composition
+
+```typescript
+import { HangulUnicodeComposer, HangulTextEvent } from 'hangul-unicode-composer';
+
+const composer = new HangulUnicodeComposer();
+
+// Listen to update events
+composer.addEventListener(HangulTextEvent.UPDATE, (e) => {
+  const ev = e as HangulTextEvent;
+  console.log('Composed text:', ev.string); 
+});
+
+// Or use a simple callback property
+composer.onUpdate = (text) => {
+  console.log('Current buffer:', text);
+};
+
+// Type some Korean characters
+composer.addJamo('ㅎ'); // 'ㅎ'
+composer.addJamo('ㅏ'); // '하'
+composer.addJamo('ㄴ'); // '한'
+composer.addJamo('ㄱ'); // '한', 'ㄱ' carries over to the next syllable
+composer.addJamo('ㅜ'); // '한구'
+composer.addJamo('ㄱ'); // '한국'
+
+console.log(composer.compositionString); // "한"
+console.log(composer.extra);             // "국"
+console.log(composer.compositionString + composer.extra); // "한국"
+```
+
+### 2. Backspacing and Resetting
+
+```typescript
+composer.backSpace(); // '한구'
+composer.backSpace(); // '한'
+composer.space();     // '한 '
+composer.reset();     // clears everything
+```
+
+### 3. State Archiving and Restoring
+Ideal for applications swapping input focus across multiple inputs using the same virtual keyboard instance.
+
+```typescript
+// Type first field
+composer.addJamo('ㄱ');
+composer.addJamo('ㅏ'); // '가'
+composer.archive('field1'); // Save state
+
+// Switch to second field
+composer.reset();
+composer.addJamo('ㄴ');
+composer.addJamo('ㅏ'); // '나'
+composer.archive('field2'); // Save state
+
+// Restore first field
+composer.restore('field1'); 
+console.log(composer.compositionString + composer.extra); // '가'
+```
+
+## API Reference
+
+### Properties
+* `compositionString: string` - Fully completed Hangul syllables.
+* `extra: string` - Currently active/composing syllable.
+* `restrict: number` - Max text length constraint (default: `3000`).
+* `instantChars: string[]` - Access the raw Jamo characters array in the active buffer.
+
+### Callbacks
+* `onUpdate?: (text: string) => void` - Triggers whenever text changes.
+* `onLimited?: (text: string) => void` - Triggers when text exceeds `restrict` length.
+* `onError?: (text: string) => void` - Triggers on compilation error.
+
+### Static Methods
+* `HangulUnicodeComposer.isHangulJaeum(char: string): boolean`
+* `HangulUnicodeComposer.isHangulMoeum(char: string): boolean`
+* `HangulUnicodeComposer.isHangulJamo(char: string): boolean`
+* `HangulUnicodeComposer.getString3Syllables(init: string, mid: string, fin: string): string`
+
+## License
+
+Apache License V2

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { HangulTextEvent } from "./text/HangulTextEvent.js";
+export { HangulUnicodeComposer } from "./text/HangulUnicodeComposer.js";
+export { KeyInfo } from "./keyboard/keyMeta/KeyInfo.js";
+export { KeyType } from "./keyboard/keyMeta/KeyType.js";
+export { KeyStatus } from "./keyboard/key/KeyStatus.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { HangulTextEvent } from "./text/HangulTextEvent.js";
+export { HangulUnicodeComposer } from "./text/HangulUnicodeComposer.js";
+export { KeyInfo } from "./keyboard/keyMeta/KeyInfo.js";
+export { KeyType } from "./keyboard/keyMeta/KeyType.js";
+export { KeyStatus } from "./keyboard/key/KeyStatus.js";

package/dist/keyboard/key/KeyStatus.d.ts

@@ -0,0 +1,6 @@
+export declare class KeyStatus {
+    static readonly DEFAULT = "default";
+    static readonly OVER = "over";
+    static readonly DOWN = "down";
+    static readonly FOCUS = "focus";
+}

package/dist/keyboard/key/KeyStatus.js

@@ -0,0 +1,6 @@
+export class KeyStatus {
+    static DEFAULT = "default";
+    static OVER = "over";
+    static DOWN = "down";
+    static FOCUS = "focus";
+}

package/dist/keyboard/keyMeta/KeyInfo.d.ts

@@ -0,0 +1,5 @@
+export declare class KeyInfo {
+    keyType: string;
+    keyValue: string;
+    keyValue2: string;
+}

package/dist/keyboard/keyMeta/KeyInfo.js

@@ -0,0 +1,5 @@
+export class KeyInfo {
+    keyType = "";
+    keyValue = "";
+    keyValue2 = "";
+}

package/dist/keyboard/keyMeta/KeyType.d.ts

@@ -0,0 +1,14 @@
+export declare class KeyType {
+    /**
+     * Normal keyboard key (character key).
+     */
+    static readonly NORMAL_KEY = "normalKey";
+    /**
+     * Function key (Shift, Backspace, Enter, Language toggle, Space, etc.).
+     */
+    static readonly FUNC_KEY = "funcKey";
+    /**
+     * Special key (other keys outside default keyboard functionalities).
+     */
+    static readonly SPECIAL_KEY = "specialKey";
+}

package/dist/keyboard/keyMeta/KeyType.js

@@ -0,0 +1,14 @@
+export class KeyType {
+    /**
+     * Normal keyboard key (character key).
+     */
+    static NORMAL_KEY = "normalKey";
+    /**
+     * Function key (Shift, Backspace, Enter, Language toggle, Space, etc.).
+     */
+    static FUNC_KEY = "funcKey";
+    /**
+     * Special key (other keys outside default keyboard functionalities).
+     */
+    static SPECIAL_KEY = "specialKey";
+}

package/dist/text/HangleTextEvent.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Event class used in HangleUnicodeComposer.
+ * Replicates the AS3 HangleTextEvent behaviour.
+ */
+export declare class HangleTextEvent extends Event {
+    /**
+     * Dispatched when the composed string changes.
+     */
+    static readonly UPDATE = "update";
+    /**
+     * Dispatched when the composed string length reaches the restricted limit.
+     */
+    static readonly LIMITED = "limited";
+    /**
+     * Dispatched when composition errors occur.
+     */
+    static readonly ERROR = "error";
+    /**
+     * Composed string data at the time of the event.
+     */
+    string: string;
+    constructor(type: string, stringData: string, bubbles?: boolean, cancelable?: boolean);
+    toString(): string;
+}

package/dist/text/HangleTextEvent.js

@@ -0,0 +1,29 @@
+/**
+ * Event class used in HangleUnicodeComposer.
+ * Replicates the AS3 HangleTextEvent behaviour.
+ */
+export class HangleTextEvent extends Event {
+    /**
+     * Dispatched when the composed string changes.
+     */
+    static UPDATE = "update";
+    /**
+     * Dispatched when the composed string length reaches the restricted limit.
+     */
+    static LIMITED = "limited";
+    /**
+     * Dispatched when composition errors occur.
+     */
+    static ERROR = "error";
+    /**
+     * Composed string data at the time of the event.
+     */
+    string;
+    constructor(type, stringData, bubbles = false, cancelable = false) {
+        super(type, { bubbles, cancelable });
+        this.string = stringData;
+    }
+    toString() {
+        return `${this.type} ${this.string}`;
+    }
+}

package/dist/text/HangleUnicodeComposer.d.ts

@@ -0,0 +1,133 @@
+/**
+ * HangleUnicodeComposer
+ * Ports the AS3 한글 조합 라이브러리 to TypeScript.
+ * Composes Korean Jamo characters into Unicode Hangul syllables.
+ */
+export declare class HangleUnicodeComposer extends EventTarget {
+    /**
+     * Initial consonant (초성) Unicode values
+     */
+    private static readonly INITIAL;
+    /**
+     * Medial vowel (중성) Unicode values
+     */
+    private static readonly MEDIAL;
+    /**
+     * Final consonant (종성) Unicode values. Index 0 is empty (no final consonant).
+     */
+    private static readonly FINAL;
+    private static used;
+    /**
+     * Helper to make one letter by composing 3 syllables.
+     */
+    static getString3Syllables(init: string, mid: string, fin: string): string;
+    /**
+     * Returns true if the character is a Hangeul Jaeum (consonant) in the range 3131 ~ 314E.
+     */
+    static isHangleJaeum(char: string): boolean;
+    /**
+     * Returns true if the character is a Hangeul Jamo in the range 3130 ~ 318F.
+     */
+    static isHangleJamo(char: string): boolean;
+    /**
+     * Returns true if the character is a Hangeul Moeum (vowel) in the range 314F ~ 3163.
+     */
+    static isHangleMoeum(char: string): boolean;
+    compositionString: string;
+    extra: string;
+    restrict: number;
+    private instant;
+    private archives;
+    onUpdate?: (text: string) => void;
+    onLimited?: (text: string) => void;
+    onError?: (text: string) => void;
+    constructor();
+    ver(): string;
+    get instantChars(): string[];
+    set instantChars(value: string[]);
+    /**
+     * Input Jaeum or Moeum to compose.
+     */
+    addJamo(char: string): void;
+    /**
+     * Save current composed strings by key.
+     */
+    archive(key: string, txt?: string | null): number;
+    /**
+     * Restore composed state from the saved key.
+     */
+    restore(key: string): string;
+    /**
+     * Logic engine to process the composition of characters in instant array.
+     */
+    private instantUpdate;
+    /**
+     * Helper to dispatch events and invoke corresponding callbacks.
+     */
+    private dispatchComposerEvent;
+    /**
+     * Insert character that is not available to compose (e.g. English, numbers, symbols).
+     */
+    addSpecialChar(char: string, at?: number): void;
+    /**
+     * Add Jamo by Unicode character code.
+     */
+    addJamoUnicode(code: number): void;
+    /**
+     * Delete character by backspace.
+     */
+    backSpace(at?: number): void;
+    /**
+     * Composes two Jamos and returns array with composed character or split ones.
+     */
+    compare2Jamo(charA: string, charB: string): string[];
+    /**
+     * Composes three Jamos.
+     */
+    compare3Syllables(init: string, mid: string, fin: string): string[];
+    /**
+     * Checks if string is a valid Hangul syllable or Jamo.
+     */
+    compatibleHangleJamo(char: string): boolean;
+    /**
+     * Checks if character is a Jaeum.
+     */
+    compatibleJaeum(char: string): boolean;
+    /**
+     * Checks if character is a Moeum.
+     */
+    compatibleMoeum(char: string): boolean;
+    /**
+     * Deletes characters at target index.
+     */
+    del(at?: number): void;
+    /**
+     * Resets composer state.
+     */
+    reset(): void;
+    /**
+     * Checks if character is in FINAL.
+     */
+    isFinalJamo(char: string): boolean;
+    /**
+     * Checks if character is in INITIAL.
+     */
+    isInitialJamo(char: string): boolean;
+    /**
+     * Checks if character is in MEDIAL.
+     */
+    isMedialJamo(char: string): boolean;
+    /**
+     * Adds space.
+     */
+    space(at?: number): void;
+    /**
+     * Combines initial, medial, and final into a single Hangul syllable.
+     */
+    combine3Syllables(init: string, mid: string, fin: string): string;
+    /**
+     * Combine two characters (Jaeum + Jaeum, Moeum + Moeum, or Initial + Medial)
+     */
+    private combine;
+    private isCombinableFinalJamo;
+}