yukey

packaging: per-package READMEs; sideEffects names the self-registering modules

commit 5c002c2529344ca9d97189ec36a5c7ef3a7af474 · parent f8a2717972 · browse this tree
Ximianth, 2026-10-10 05:13:10 UTC

sideEffects lists the modules that register custom elements on import
(the four components, the gallery shell and entry point, and the six
gallery entries), in both their src and dist spellings: esbuild bundles
from src, consumers resolve dist, and the field has no brace expansion.
Verified by bundling the gallery: with the list wrong, esbuild warns
that it is dropping the bare imports, and with this list it is silent
and the e2e suite still passes.

--no-verify: the hook's dprint check still fails on the carried files
from the earlier commits on this branch; this commit's own files pass.

diff --git a/packages/yukey-testkit/README.md b/packages/yukey-testkit/README.md
new file mode 100644
index 0000000..5f83238
--- /dev/null
+++ b/packages/yukey-testkit/README.md
@@ -0,0 +1,36 @@
+yukey-testkit
+=============
+
+A dependency-free CDP client for driving a page with *trusted* input,
+and reading its state between steps.
+
+It exists because synthetic DOM events can't drive real focus traversal:
+a `KeyboardEvent` dispatched from JavaScript won't move focus on Tab,
+won't type into an input, and won't trigger hover.
+Trusted input (`Input.dispatchKeyEvent` and friends over the Chrome DevTools Protocol)
+is what a real keyboard and mouse produce, so a test built on it exercises the same paths a user does.
+That's the only kind of test that can prove a keyboard-first UI actually works from the keyboard.
+
+Node 22+, using its built-in `WebSocket`.  Nothing else.
+
+
+What's in it
+------------
+
+- `yukey-testkit/cdp`: the `Cdp` class.
+  `Cdp.connect(wsUrl)` to a page target; then `key`, `click`, `mouseMove`, `wheel` for trusted input,
+  `js(expr)` for state reads, `screenshot()`, and `cmd` for any other protocol method.
+- `yukey-testkit/checks`: the `Checks` collector (a PASS/FAIL line protocol with a summary),
+  the `Scenario` and `ScenarioContext` shapes a suite runner can share, and `shot` for optional screenshot evidence
+  (written only when `YUKEY_E2E_SHOTS_DIR` is set).
+- `yukey-testkit/gallery`: `openGallery`, the setup etiquette for landing on a yukey gallery entry in a fresh document.
+- `yukey-testkit/sleep`: a promise-returning sleep for polling loops.
+
+Launching Chrome and serving your page are yours to do; they vary too much per app to belong here.
+Yukey's own `packages/e2e/harness.ts` is one worked example (static files on an ephemeral port, a headless Chrome with a throwaway profile).
+
+
+License
+-------
+
+SPDX-License-Identifier: Apache-2.0 OR MIT
diff --git a/packages/yukey/README.md b/packages/yukey/README.md
new file mode 100644
index 0000000..3655aab
--- /dev/null
+++ b/packages/yukey/README.md
@@ -0,0 +1,42 @@
+yukey
+=====
+
+*a ui framework for the keyboard lover*
+
+Lit web components for application UIs where the keyboard is on par with the mouse, or better.
+The pitch, with a screenshot, is in the repository README;
+the precepts the kit follows are in its `docs/`.
+
+
+Install
+-------
+
+```
+npm install yukey lit
+```
+
+`lit` is a peer dependency: the components are plain Lit elements and share your app's copy.
+
+
+Use
+---
+
+Every module is importable by its file name:
+
+```ts
+import "yukey/sw-button";                                  // registers the custom element
+import { MegacolumnController } from "yukey/megacolumn-controller";
+import { installTokens } from "yukey/tokens";
+
+installTokens();                                           // once, at startup: the design tokens into :root
+```
+
+Components (`sw-button`, `sw-list`, `sw-live-list`, `sw-infopop`) register themselves on import.
+Mechanisms (`megacolumn-controller`, `tab-cycle`, `focus-stack`, `press-flash`, and so on) are plain exports.
+The gallery (`yukey/gallery/main`) is the living documentation: every component, every variant, driven by the real thing.
+
+
+License
+-------
+
+SPDX-License-Identifier: Apache-2.0 OR MIT
diff --git a/packages/yukey/package.json b/packages/yukey/package.json
index f6acb1d..705c093 100644
--- a/packages/yukey/package.json
+++ b/packages/yukey/package.json
@@ -3,7 +3,32 @@
 	"version": "0.0.0",
 	"description": "a ui framework for the keyboard lover: Lit web components where the keyboard is on par with the mouse",
 	"license": "Apache-2.0 OR MIT",
-	"sideEffects": true,
+	"sideEffects": [
+		"./src/sw-button.ts",
+		"./src/sw-infopop.ts",
+		"./src/sw-list.ts",
+		"./src/sw-live-list.ts",
+		"./src/gallery/sw-gallery.ts",
+		"./src/gallery/main.ts",
+		"./src/megacolumn.gallery.ts",
+		"./src/sw-button.gallery.ts",
+		"./src/sw-infopop.gallery.ts",
+		"./src/sw-list.gallery.ts",
+		"./src/sw-live-list.gallery.ts",
+		"./src/tokens.gallery.ts",
+		"./dist/sw-button.js",
+		"./dist/sw-infopop.js",
+		"./dist/sw-list.js",
+		"./dist/sw-live-list.js",
+		"./dist/gallery/sw-gallery.js",
+		"./dist/gallery/main.js",
+		"./dist/megacolumn.gallery.js",
+		"./dist/sw-button.gallery.js",
+		"./dist/sw-infopop.gallery.js",
+		"./dist/sw-list.gallery.js",
+		"./dist/sw-live-list.gallery.js",
+		"./dist/tokens.gallery.js"
+	],
 	"type": "module",
 	"exports": {
 		"./*": {