@kkeyboard/web

The web package exposes two layers:

• createWebInputController: host-neutral keyboard behavior for a textarea, input, contenteditable adapter, or editor integration.
• createWebInputComponent: a small framework-free DOM component that wires a host input to a caret-relative suggestion dropdown.
• createContentEditableAdapter: a small host adapter for contenteditable editors, suitable for a WYSIWYG sample or a later Tiptap/ProseMirror wrapper.
• getWebLocale: English and Khmer labels for host-controlled option panels and suggestion accessibility text.

The component keeps the engine independent from React, Svelte, Vue, rich-text editors, and native keyboard adapters. Those integrations can either use the controller directly or wrap the DOM component.

Component contract

import { createWebInputComponent } from "@kkeyboard/web";

const input = createWebInputComponent({
  editor: document.querySelector("#editor"),
  inputShell: document.querySelector(".input-shell"),
  editorCard: document.querySelector(".editor-card"),
  suggestionPopover: document.querySelector("#suggestion-popover"),
  candidatesElement: document.querySelector("#candidates"),
  navigationElement: document.querySelector("#candidate-navigation"),
  engine,
  boundary: " ",
  completionBoundary: "\u200b",
  getInputSettings: () => ({
    mode: "auto",
    register: "auto",
    completionEnabled: true,
    // Optional; next-word prediction is disabled unless explicitly enabled.
    nextWordSuggestionsEnabled: true,
  }),
});

// Later, when the host is removed:
input.destroy();

The host remains the source of truth for text and selection. The component handles input, selection changes, cursor-relative placement, keyboard navigation, candidate rendering, acceptance, dismissal, and whole committed word deletion. A physical Space can remain a normal visible space while an accepted suggestion uses a separate invisible completion boundary.

Current-word completion is enabled by default. Next-word prediction is opt-in: set nextWordSuggestionsEnabled: true when the host wants it.

For a custom editor, use the controller directly and provide readHostState/replaceHostRange instead of relying on textarea APIs. For a contenteditable host, createContentEditableAdapter provides those functions and can be passed to createWebInputComponent.

The component does not impose a UI language. Hosts can pass translated labels to their own controls and use getNavigationLabels to localize suggestion navigation text. The sample includes English/Khmer switching for this layer.

Browser asset caching and preferences

The web package also provides optional host-controlled helpers for production runtime assets and UI settings:

import {
  loadCachedResponse,
  readWebInputPreferences,
  writeWebInputPreferences,
} from "@kkeyboard/web";

const response = await loadCachedResponse("/assets/runtime-core.bundle", {
  cacheName: "my-app-kkeyboard-runtime-v1",
});
const preferences = readWebInputPreferences({
  key: "my-app.kkeyboard.preferences.v1",
  defaults: { completionEnabled: true },
});
writeWebInputPreferences(preferences, {
  key: "my-app.kkeyboard.preferences.v1",
});

loadCachedResponse uses Cache Storage when available, returns a cached asset immediately, and refreshes it in the background. Use an application-specific cache name and bump its version when the runtime format changes. Native clients should use their platform equivalent rather than browser storage.

The preference helpers use localStorage when available and fall back to a small same-origin cookie for embedded browsers that expose but restrict localStorage. Hosts can pass explicit storage and document adapters for tests or non-browser runtimes.