Hacking🔗

Build & check🔗

Toolchain prerequisites: node 22+.

make setup      # npm install + activates the pre-commit hook
make check      # dprint verify, typecheck, unit tests -- what the pre-commit hook runs
make fmt        # apply dprint
make build      # emits dist/ for the publishable packages, and bundles the gallery
make check-e2e  # drives the gallery in a headless Chrome with trusted input; not part of check
make publish    # npm publish for the public packages

Run make alone for the full target list.

Layout🔗

This is an npm workspace. The root package.json is private and fans out to packages/*:

• packages/yukey/ -- the kit. Published. Components (src/yk-*.ts) and their mechanisms, the default theme, and the component gallery (src/gallery/, bundled to static/gallery.js). Unit tests live beside their subject as src/*.test.ts.
• packages/yukey-testkit/ -- a dependency-free CDP client for driving a page with trusted input. Published. Node-only; it exists so that apps built on yukey (and yukey's own e2e suite) can test real keyboard traversal, which synthetic DOM events can't do.
• packages/e2e/ -- yukey's own end-to-end suite. Private. Serves the gallery bundle, launches a headless Chrome, runs scenarios against the gallery entries.
• docs/ -- the precepts (what yukey's design follows) and, as they appear, guides for composing with it.

Things worth knowing🔗

• The published packages ship dist/ (.js + .d.ts + maps), not .ts. Lit's decorators require experimentalDecorators and useDefineForClassFields: false; compiling here means consumers don't have to match those flags. Consequence: anything consuming yukey via a file: dependency must make build here first.
• packages/e2e imports yukey-testkit through the workspace symlink. The testkit's exports map carries a yukey-source condition pointing at src/*.ts; the e2e package's tsconfig (customConditions) and its node invocation (--conditions=yukey-source) both select it, so typechecking and running the suite never require a testkit build. The default condition still resolves to dist/, which is what every outside consumer gets.
• The e2e suite needs a Chromium. It defaults to /headless-shell/headless-shell; YUKEY_E2E_CHROME overrides. Chrome is launched with --no-sandbox (fine for headless-shell in a container; worth knowing if you point it at a desktop Chrome).