press-flash: the consumers list moves onto PRESSED_CLASS, the token note onto pressMs
commit dc3841c6d21eb095bcf694047cc71b54876d85d6 · parent cbbd2a4a97
· browse this tree
Ximianth, 2026-10-18 10:48:21 UTC
The header's "consumers and their class carriers" bullets are about who carries the class, so they live on PRESSED_CLASS; the design-token sentence is about the duration, so it lives on pressMs beside its throw rule. flashPress keeps its own doc as a /** */ block. The header keeps the purpose. Wording is unchanged apart from name-first prefixes; lines break at clauses.
diff --git a/packages/yukey/src/press-flash.ts b/packages/yukey/src/press-flash.ts index 0db8626..8b382cd 100644 --- a/packages/yukey/src/press-flash.ts +++ b/packages/yukey/src/press-flash.ts @@ -1,22 +1,23 @@ -// Activation feedback, shared across widgets: the "yk-pressed" flash class that -// acknowledges a successful activation for --yk-press-ms, so keyboard triggers -// (Enter/Space, hotkeys) are as visible as a mouse press. The duration is one -// system-wide design token, read from the live cascade at flash time -- so an -// accessibility mode can slow every flash by restyling one custom property. -// -// Consumers and their class carriers: -// - yk-button flashes its host element (and manages its own pointer-held -// "yk-held" class beside it); its styles render both. -// - Megacolumn hosts with plain activatable rows call flashPress(rowElement) -// when they act on a forwarded activation; the row-flavored .yk-pressed -// rendering lives in megacolumnStyles, beside the focus washes it must outrank. +// Activation feedback, shared across widgets: +// the "yk-pressed" flash class that acknowledges a successful activation for --yk-press-ms, +// so keyboard triggers (Enter/Space, hotkeys) are as visible as a mouse press. +/** + * PRESSED_CLASS is the flash class. Consumers and their class carriers: + * - yk-button flashes its host element (and manages its own pointer-held "yk-held" class beside it); + * its styles render both. + * - Megacolumn hosts with plain activatable rows call flashPress(rowElement) when they act on a forwarded activation; + * the row-flavored .yk-pressed rendering lives in megacolumnStyles, beside the focus washes it must outrank. + */ export const PRESSED_CLASS = "yk-pressed"; -// The flash duration, resolved from the cascade at el. Throws when the property -// does not resolve (tokens not installed, or a detached element): a feedback -// system that silently picks its own duration would hide exactly the -// misconfiguration it exists to surface. +/** + * pressMs is the flash duration, resolved from the cascade at el. + * The duration is one system-wide design token, read from the live cascade at flash time -- + * so an accessibility mode can slow every flash by restyling one custom property. + * Throws when the property does not resolve (tokens not installed, or a detached element): + * a feedback system that silently picks its own duration would hide exactly the misconfiguration it exists to surface. + */ export function pressMs(el: Element): number { const raw = getComputedStyle(el).getPropertyValue("--yk-press-ms").trim(); const m = /^(\d+(?:\.\d+)?)(m?s)$/.exec(raw); @@ -32,9 +33,11 @@ export function pressMs(el: Element): number { const timers = new WeakMap<HTMLElement, number>(); -// Show the pressed look on el for --yk-press-ms. A re-flash while one is still -// showing re-arms the timer, so rapid activations read as sustained activity -// instead of getting cut short by the first flash's expiry. +/** + * flashPress shows the pressed look on el for --yk-press-ms. + * A re-flash while one is still showing re-arms the timer, + * so rapid activations read as sustained activity instead of getting cut short by the first flash's expiry. + */ export function flashPress(el: HTMLElement): void { el.classList.add(PRESSED_CLASS); window.clearTimeout(timers.get(el));