yukey

megacolumn-controller, yk-live-list: body comments point at the declarations their content moved to

commit 33b2f71cb8fb9c85f6636d14d4af1aea86b06b89 · parent 19cdc86d8c · browse this tree
Ximianth, 2026-10-24 10:49:54 UTC

Three body comments still said "see the header" for the DOM contract
and the focus-change contract, which the docs round moved onto
MegacolumnController and MegacolumnFocusChangeDetail.  They're //
comments, so they name the declaration rather than {@link} it.

closedToSight is exported: the class doc links it as the one
closed-row predicate, and an unexported target renders as plain text in
the .d.ts.  The [data-info] bullet names YkInfoDetail, the declaration
that holds the info norm's wiring, alongside the file.

diff --git a/packages/yukey/src/megacolumn-controller.ts b/packages/yukey/src/megacolumn-controller.ts
index aa1d3c3..329cbe5 100644
--- a/packages/yukey/src/megacolumn-controller.ts
+++ b/packages/yukey/src/megacolumn-controller.ts
@@ -116,7 +116,7 @@ type Host = ReactiveControllerHost & { renderRoot: DocumentFragment | HTMLElemen
  * - Match by value, never by attribute presence:
  *   aria-hidden="false" behaves inconsistently in browsers and must never read as hidden here.
  */
-function closedToSight(el: HTMLElement): boolean {
+export function closedToSight(el: HTMLElement): boolean {
 	return el.closest("[aria-hidden=\"true\"]") !== null;
 }
 
@@ -168,7 +168,7 @@ function closedToSight(el: HTMLElement): boolean {
  *   (the guidelines' example: a map move order is cheap to cancel, so just give the order;
  *   a text dive is undone by Escape, nothing committed).
  *   If reaching for this makes you think twice, that is the design working.
- * - `[data-info="<content>"]`: the info norm's carrier attribute (SSOT: yk-info.ts).
+ * - `[data-info="<content>"]`: the info norm's carrier attribute (SSOT: `YkInfoDetail`, yk-info.ts).
  *   When a forwarded i comes back unclaimed,
  *   the container answers for the nearest carrier from the focused control up to the row (inclusive),
  *   dispatching yk-info itself -- so plain rows get the i norm with no widget code.
@@ -268,7 +268,7 @@ export class MegacolumnController implements ReactiveController {
 			container.addEventListener("focusin", (e) => this.onFocusin(e));
 			container.addEventListener("focusout", (e) => this.onFocusout(e));
 			// Components whose rows change outside host renders announce it with this
-			// event (see the header); a render-driven scan happens in hostUpdated as always.
+			// event (see the MegacolumnController class doc); a render-driven scan happens in hostUpdated as always.
 			container.addEventListener("megacolumn-rescan", () => {
 				this.scanRows(this.mustContainer());
 				this.applyFocusState();
@@ -435,7 +435,7 @@ export class MegacolumnController implements ReactiveController {
 			"mc-empty-focus",
 			focusedId === null && this.focusIsInside(container),
 		);
-		// Announce focus identity changes (see the header's megacolumn-focus-change
+		// Announce focus identity changes (the MegacolumnFocusChangeDetail
 		// contract).  Dispatched here, the one place every cause converges -- arrows,
 		// Home/End, hotkey jumps, churn fallbacks, focus requests -- and after the
 		// scroll above, so a listener reading anchor geometry sees the settled row.
diff --git a/packages/yukey/src/yk-live-list.ts b/packages/yukey/src/yk-live-list.ts
index cfe5c0d..05d63a9 100644
--- a/packages/yukey/src/yk-live-list.ts
+++ b/packages/yukey/src/yk-live-list.ts
@@ -889,7 +889,7 @@ export class YkLiveList<T = unknown> extends LitElement {
 		// closed to sight and closed to navigation together.
 		const closed = row.phase === "pending" || row.phase === "collapsing";
 		const phase: LiveListPhase = row.phase === "committed" || row.phase === "collapsing" ? "committed" : "live";
-		// Mega mode stamps row identity for the megacolumn scan (see the header).
+		// Mega mode stamps row identity for the megacolumn scan (the MegacolumnController class doc has the attribute contract).
 		// classMap (not string interpolation) because the megacolumn controller stamps
 		// its focus classes on these elements imperatively, and an interpolated class
 		// attribute would wipe them on the next content tick.