kurdish-keyboard

An embeddable virtual keyboard for typing Kurdish in the browser — both Kurmanji (Latin script) and Sorani (Arabic script) — as a TypeScript npm package. No OS-level keyboard layouts, no native apps: attach it to any <input> or <textarea> on any modern site.

Status: v0.1.1. Three layouts (CLDR-seeded Sorani, two Kurmanji variants), live script toggling, mobile modes, WAI-ARIA accessibility, theming, and a legacy-text normalizer — all verified by 90 tests and an executable packaging spec. The live demo and landing pages ship in six languages.

Why

Kurdish text on the web suffers from decades of codepoint fragmentation — visually identical letters encoded differently (ك vs ک, ي vs ی, ه vs ە), which silently breaks search, sorting, and spellcheck. This keyboard emits only the unified codepoints standardized by the KRG Department of IT and verified against the Unicode Character Database, so everything typed with it is correct by construction. See proposal/002-Proposal.md for the full design and proposal/001-idea-research.md for the primary-source research behind it.

Usage

import { KurdishKeyboard } from 'kurdish-keyboard';
import 'kurdish-keyboard/styles.css'; // optional styling (responsive + touch targets)
import sorani from 'kurdish-keyboard/layouts/sorani';
import kurmanjiPhonetic from 'kurdish-keyboard/layouts/kurmanji-phonetic';

const input = document.querySelector('input')!;
const kb = KurdishKeyboard.attachTo(input, {
  layout: sorani,       // tree-shakable: only the layouts you import are bundled
  suppressNative: true, // mobile: keep the native keyboard hidden (inputmode="none")
  position: 'docked',   // or 'inline' (default) / 'floating'
});
kb.setLayout(kurmanjiPhonetic); // live script toggle (RTL ↔ LTR)
kb.detach();

Full reference — options, layouts, mobile, theming (--kkb-*), accessibility, the legacy-text normalizer, CDN usage, and platform limits — lives in the integration guide.

Try the demo

Live: kurdish-keyboard.vercel.app — the playground, plus the landing page in five languages (en · kmr · ckb · fa · tr). Every push to main redeploys.

Or run it locally:

git clone https://github.com/shaho/kurdish-keyboard.git
cd kurdish-keyboard
npm install
npm run demo

npm run demo starts a local dev server (vite) and opens the demo page in your browser. Click into the input or textarea, place the caret or select some text, and press the on-screen keys — the panel types into the focused field and the page shows each input event as frameworks would observe it.

Development

npm run test        # vitest suite (jsdom)
npm run typecheck   # tsc --noEmit (TypeScript 7, strict)
npm run build       # tsup (ESM + CJS) + tsc declaration emit → dist/
npm run demo:build  # static demo site (playground + all landing locales) → demo-dist/
npx vite preview    # serve demo-dist locally — ES modules never run from file://,
                    # so always preview through a server, not by double-clicking the HTML

The project is developed ticket by ticket with a recorded audit trail:

| Where | What | |---|---| | proposal/ | The decided v1 proposal and the research note it stands on | | docs/tasks/ | The v1 tickets, each with acceptance criteria and blocking edges | | docs/decisions/ | Decision records made during development | | report/ | Per-commit log: hash, date, description |

License

MIT