yukey

yk-info: the wiring SSOT moves onto YkInfoDetail

commit e5e792966c54f8a1cd3e483d87d3ae24792e3872 · parent dc3841c6d2 · browse this tree
Ximianth, 2026-10-18 10:48:33 UTC

The "one authored content, two triggers" contract lives on YkInfoDetail,
which yk-infopop's class doc already links as the wiring SSOT; the
producers list lives on dispatchYkInfo, which had no doc.  The source
field's "see the retargeting note above" becomes a link.  The header keeps
the purpose and the norm pointer.  Wording is unchanged apart from
lowercasing emphasis, backticks on `i`, and name-first prefixes; lines
break at clauses.

diff --git a/packages/yukey/src/yk-info.ts b/packages/yukey/src/yk-info.ts
index 279a9c9..6801083 100644
--- a/packages/yukey/src/yk-info.ts
+++ b/packages/yukey/src/yk-info.ts
@@ -1,28 +1,33 @@
 // The info norm's wiring: the yk-info event shape and the data-info carrier contract.
-// This file is the SSOT for both.  (The norm itself: docs/precepts-we-love-the-keyboard.md,
-// "info pops" -- i means "info, please" on almost any element.)
-//
-// One authored content, two triggers:
-//
-//   - `data-info="<content>"` on any element makes it a CARRIER.  yk-infopop's
-//     hover trigger finds carriers by this attribute, and the megacolumn
-//     controller answers otherwise-unclaimed i forwards for them.  Components
-//     with an info property (yk-button) mirror it onto this attribute;
-//     plain markup writes the attribute directly.  Empty means not a carrier.
-//   - `yk-info` (bubbles + composed) is the keyboard trigger's event: a producer
-//     that answered i dispatches it, yk-infopop renders it.  The detail carries
-//     the anchor element because composed events retarget: a listener outside
-//     the shadow tree sees only the host chain, never the real source.
-//
-// Producers today: yk-button (its own i claim, standalone and in rows) and
-// MegacolumnController (the fallback for plain [data-info] rows).
+// This file is the SSOT for both, on YkInfoDetail.
+// (The norm itself: docs/precepts-we-love-the-keyboard.md, "info pops" -- i means "info, please" on almost any element.)
 
+/**
+ * YkInfoDetail is the `yk-info` event's detail, and the SSOT for the info norm's wiring.
+ * One authored content, two triggers:
+ *
+ * - `data-info="<content>"` on any element makes it a carrier.
+ *   yk-infopop's hover trigger finds carriers by this attribute,
+ *   and the megacolumn controller answers otherwise-unclaimed `i` forwards for them.
+ *   Components with an info property (yk-button) mirror it onto this attribute; plain markup writes the attribute directly.
+ *   Empty means not a carrier.
+ * - `yk-info` (bubbles + composed) is the keyboard trigger's event:
+ *   a producer that answered `i` dispatches it ({@link dispatchYkInfo}), yk-infopop renders it.
+ *   The detail carries the anchor element because composed events retarget:
+ *   a listener outside the shadow tree sees only the host chain, never the real source.
+ */
 export interface YkInfoDetail {
 	content: string;
-	// The element to anchor the popup to (see the retargeting note above).
+
+	/** source is the element to anchor the popup to (see the retargeting note on {@link YkInfoDetail}). */
 	source: HTMLElement;
 }
 
+/**
+ * dispatchYkInfo dispatches a `yk-info` event from source.
+ * Producers today: yk-button (its own `i` claim, standalone and in rows)
+ * and MegacolumnController (the fallback for plain [data-info] rows).
+ */
 export function dispatchYkInfo(source: HTMLElement, content: string): void {
 	source.dispatchEvent(
 		new CustomEvent<YkInfoDetail>("yk-info", {