From c5ca8b7d7ac1aa751c1bf79ad35b178f96b3ba77 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Tue, 23 Jun 2026 19:34:01 -0400 Subject: feat(theme-studio): locate preview elements by hover and click Hovering a data-face preview element shows its section, face, and effective value in the preview-label info line, and the element's title carries the full record: effective fg/bg plus a per-attribute source note (direct, inherited-from-X, default, or cleared-rendering-as-default). Clicking an on-pane element scrolls to and flashes its assignment row. Off-pane and cross-surface elements stay hover-only. A single owner-qualified registry keyed by {owner, face} backs both data-face surfaces, package and UI, so the same face name under two owners never collides. The pure helpers in app-core.js take all state as arguments and return data. The one stateful adapter, previewSpan, lives in previews.js and emits the escaped markup. os() stays a package-owner wrapper over previewSpan, and a unified locateClick dispatcher replaces the per-surface click branches. Covered by test-locate.mjs and four new browser gates. Full harness green. --- scripts/theme-studio/theme-studio.html | 373 ++++++++++++++++++++++++++++++++- 1 file changed, 366 insertions(+), 7 deletions(-) (limited to 'scripts/theme-studio/theme-studio.html') diff --git a/scripts/theme-studio/theme-studio.html b/scripts/theme-studio/theme-studio.html index 4896a2387..4a3ec4fe1 100644 --- a/scripts/theme-studio/theme-studio.html +++ b/scripts/theme-studio/theme-studio.html @@ -182,6 +182,9 @@ .mock .fr{width:14px;flex:0 0 auto;border-right:1px solid #ffffff14} .mock .num{width:36px;flex:0 0 auto;text-align:right;padding-right:10px} .mock .cd{flex:1;padding-left:8px} .mock .bar,.mock .echo{padding:4px 10px;white-space:pre} #codepre [data-k],.mock [data-k],.mock [data-face]{cursor:pointer} + /* preview-locate: an on-pane element clicks to its assignment row, so it shows a + pointer; off-pane / unassigned elements are hover-only and keep the default cursor. */ + .locate-onpane{cursor:pointer} @keyframes flashcell{0%,55%{background:#e8bd3066}100%{background:transparent}} tr.flash td{animation:flashcell 1.1s ease-out} @keyframes flashtok{0%,55%{background:#e8bd30aa;color:#000}100%{background:transparent}} @@ -309,6 +312,16 @@ const DEFAULT_SYNTAX=JSON.parse(JSON.stringify(SYNTAX)); function pname(n){return nameToHex(n,PALETTE);} function seedPkgmap(){return buildPkgmap(APPS,PALETTE);} let PKGMAP=seedPkgmap(); +// Preview-locate registry (preview-locate spec). One cached, module-level +// registry rebuilt once per assignment / import / reset / view-switch batch — at +// the top of the two preview renderers (buildPkgPreview, buildMockFrame), which +// every such path funnels through before spans render. Never rebuilt per hover or +// per span. locate-onpane is recomputed from the current view at render time +// (isLocateOnPane), never stored here. Built lazily (not at declaration): the +// inlined buildLocateRegistry / UI_INHERIT from app-core.js are spliced below +// this point, so an init call here would hit the const's temporal dead zone. +let LOCATE_REG={}; +function rebuildLocateRegistry(){LOCATE_REG=buildLocateRegistry(APPS,PKGMAP,UIMAP,MAP);return LOCATE_REG;} function esc(t){return t.replace(/&/g,'&').replace(//g,'>');} // Pure color-math core (lin/rl/contrast/rating/hsv2rgb/rgb2hsv/hex2rgb/rgb2hex, // plus OKLab/OKLCH/APCA/deltaE), inlined verbatim from colormath.js. @@ -1091,6 +1104,168 @@ function composeHoverTitle(doc,base){ if(doc&&base)return doc+'\n\n'+base; return doc||base; } + +// --- preview-locate registry (preview-locate spec, Phase 0) ------------------ +// Pure helpers that turn the assignment state into a map from every data-face +// previewed element back to its owning app, effective rendered value, and the +// source of that value. All state is passed in; these return data, never HTML. +// The one stateful piece -- previewSpan, which reads the live globals and emits +// escaped HTML -- lives in previews.js, not here. + +const UI_SECTION_LABEL='UI faces'; + +// Owner-qualified registry key. owner is '@ui' for the UI surface or an app-key +// for a package; the owner already disambiguates the surface, so (owner, face) is +// the unique identity. The space separator is safe because Emacs face and app +// keys never contain spaces, so the same face name under two owners can never +// collapse to one key. +function locateKey(owner,face){return owner+''+face;} + +// Walk an inherit chain for ATTR from FACENAME, returning {value, from}: +// value -- the first truthy value up the chain, or null +// from -- the face name the value was actually set on when it was reached by +// inheritance, or null when FACENAME carries it directly +// getFace(name) returns the face object; nextName(name) gives the parent face name +// (the face's own :inherit for a package, the UI_INHERIT entry for a ui face). A +// seen-set guards against a cycle. Mirrors effResolve / resolveUiAttr's truthiness +// so the resolved value matches what the preview actually renders. +function resolveLocateAttr(faceName,getFace,nextName,attr){ + const seen={};let name=faceName,origin=true; + while(name&&!seen[name]){ + seen[name]=1; + const f=getFace(name); + if(f&&f[attr])return {value:f[attr],from:origin?null:name}; + name=nextName(name);origin=false; + } + return {value:null,from:null}; +} + +// The non-default structural attributes worth naming in a locate title. Weight +// 'normal'/slant 'normal'/height 1 are the defaults and stay out. +function locateAttrs(f){ + f=f||{};const out={}; + if(f.weight&&f.weight!=='normal')out.weight=f.weight; + if(f.slant&&f.slant!=='normal')out.slant=f.slant; + if(f.underline)out.underline=true; + if(f.strike)out.strike=true; + if(f.box)out.box=true; + if(f.inverse)out.inverse=true; + if(f.extend)out.extend=true; + if(f.height&&f.height!==1)out.height=f.height; + if(f.inherit)out.inherit=f.inherit; + return out; +} + +// Build one registry entry: effective fg/bg (matching the rendered pixels) plus a +// per-attribute source note. fg floors to the default foreground (floorFg) when +// nothing up the chain is set; bg has no floor (an unset bg draws no background), +// so an unset, non-cleared bg simply has no value and no note. A 'cleared' face +// notes the cleared state so the tooltip explains the rendered default. +function locateEntry(surface,owner,face,section,f,resolve,floorFg){ + f=f||{}; + const rf=resolve('fg'),rb=resolve('bg'); + let fgVal,fgSrc; + if(rf.value){fgVal=rf.value;fgSrc=rf.from?{kind:'inherited',from:rf.from}:{kind:'direct',from:null};} + else{fgVal=floorFg;fgSrc=(f.source==='cleared')?{kind:'cleared',from:null}:{kind:'default',from:null};} + let bgVal=null,bgSrc=null; + if(rb.value){bgVal=rb.value;bgSrc=rb.from?{kind:'inherited',from:rb.from}:{kind:'direct',from:null};} + else if(f.source==='cleared'){bgSrc={kind:'cleared',from:null};} + return {surface,owner,face,section,value:{fg:fgVal,bg:bgVal},attrs:locateAttrs(f),sources:{fg:fgSrc,bg:bgSrc}}; +} + +// The derived {surface, owner, face} -> value/attributes/source registry over the +// two data-face surfaces: package faces (PKGMAP, keyed by app-key, inherit via the +// face's own :inherit) and UI faces (UIMAP, keyed by '@ui', inherit via the +// built-in UI_INHERIT chain). map carries the ground floors (map.p default fg). +// Pure: every dependency is a parameter, no globals, no DOM. +function buildLocateRegistry(apps,pkgmap,uimap,map){ + const reg={},floorFg=(map&&map.p)||null; + for(const app in (pkgmap||{})){ + const section=(apps&&apps[app]&&apps[app].label)||app,faces=pkgmap[app]; + for(const face in faces){ + reg[locateKey(app,face)]=locateEntry('package',app,face,section,faces[face], + attr=>resolveLocateAttr(face,n=>faces[n],n=>(faces[n]&&faces[n].inherit)||null,attr),floorFg); + } + } + for(const face in (uimap||{})){ + reg[locateKey('@ui',face)]=locateEntry('ui','@ui',face,UI_SECTION_LABEL,uimap[face], + attr=>resolveLocateAttr(face,n=>uimap[n],n=>UI_INHERIT[n]||null,attr),floorFg); + } + return reg; +} + +// Look up one owner-qualified face's meta. A face not in the registry resolves to +// no owning app -- an {unassigned} marker the caller renders hover-only (never a +// dead click), not a thrown error. +function locateFaceMeta(owner,face,registry){ + const e=registry&®istry[locateKey(owner,face)]; + return e||{owner,face,unassigned:true}; +} + +// The owner-aware membership check the preview gate calls: the entry's attributes +// when (owner, face) is a known face of that owner, null when it isn't (a bad +// owner is rejected). A known face with no non-default attributes returns {} -- +// still truthy, so membership reads cleanly off the result. +function previewFaceAttrs(owner,face,registry){ + const e=registry&®istry[locateKey(owner,face)]; + return e?e.attrs:null; +} + +// Clickable predicate: an element is on-pane only when its owner is the pane being +// viewed. Recomputed from the current view at render time (never stored in the +// registry), since switching panes changes clickability but not ownership. +function isLocateOnPane(owner,currentApp){return owner===currentApp;} + +// The human source note for one resolved attribute, or null when there's no note. +function locateSourceNote(src,attr){ + if(!src)return null; + if(src.kind==='direct')return 'direct'; + if(src.kind==='inherited')return 'inherited from '+src.from; + if(src.kind==='cleared')return 'cleared, rendering as default'; + if(src.kind==='default')return attr==='bg'?'default background':'default foreground'; + return null; +} + +// The non-default structural attributes as a flat label list for the title. +function locateAttrsList(attrs){ + attrs=attrs||{};const parts=[]; + if(attrs.weight)parts.push(attrs.weight); + if(attrs.slant)parts.push(attrs.slant); + if(attrs.underline)parts.push('underline'); + if(attrs.strike)parts.push('strike'); + if(attrs.box)parts.push('box'); + if(attrs.inverse)parts.push('inverse'); + if(attrs.extend)parts.push('extend'); + if(attrs.height)parts.push('height '+attrs.height); + if(attrs.inherit)parts.push('inherit '+attrs.inherit); + return parts; +} + +// The comma-separated title string from a meta: section, element, effective value +// (fg always; bg when set), per-attribute source note, then non-default attributes. +// An unassigned meta reads ", unassigned" (no section -- it has no owner). +function formatLocateTitle(meta){ + if(!meta||meta.unassigned)return (meta&&meta.face?meta.face+', ':'')+'unassigned'; + const parts=[meta.section,meta.face],s=meta.sources||{}; + const fgNote=locateSourceNote(s.fg,'fg'); + parts.push('fg '+meta.value.fg+(fgNote?' ('+fgNote+')':'')); + if(meta.value.bg){ + const bgNote=locateSourceNote(s.bg,'bg'); + parts.push('bg '+meta.value.bg+(bgNote?' ('+bgNote+')':'')); + }else if(s.bg&&s.bg.kind==='cleared'){ + parts.push('bg cleared, rendering as default'); + } + return parts.concat(locateAttrsList(meta.attrs)).join(', '); +} + +// The immediate-wayfinding info line shown in the preview-label area on hover: +// "section > face — value" (effective fg, plus bg when set). An unassigned meta +// reads " — unassigned". Terser than the title; the title is the full record. +function locateInfoLine(meta){ + if(!meta||meta.unassigned)return (meta&&meta.face?meta.face:'')+' — unassigned'; + const val=meta.value.fg+(meta.value.bg?' / '+meta.value.bg:''); + return meta.section+' > '+meta.face+' — '+val; +} // Pure color/UI-boundary helpers (normHex, ratingColor, textOn), inlined from // app-util.js. textOn uses rl from the colormath core above. // Pure color/UI-boundary helpers: hex-input parsing, the contrast-rating status @@ -2307,6 +2482,21 @@ function mkBoxControl(get,set,opts={}){ get,set, Object.assign({styled:true,toState:(v,cur)=>({style:v,width:(cur&&cur.width)||1,color:(cur&&cur.color)||null})},opts));} function flashRow(tr){if(!tr)return;tr.scrollIntoView({block:'center',behavior:'smooth'});tr.classList.remove('flash');void tr.offsetWidth;tr.classList.add('flash');} +// Unified preview-locate click dispatch (preview-locate spec, Phases 4-5). One +// handler for every preview surface replaces the per-surface data-face branches: +// find the clicked data-face element, resolve its owner (data-owner-app, or +// DEFAULTOWNER for a bare span emitted by the generic / auto-dim / UI-mock +// renderers that pre-date previewSpan), and flash its assignment row only when it +// is on-pane. An owner-tagged off-pane / unassigned element is inert; a bare span +// is a current-pane element by construction, so it stays clickable. No persistent +// selection — flashRow is scroll + flash only. The data-k syntax-click path stays +// separate (handled by each caller before delegating here). +function locateClick(e,defaultOwner){ + const u=e.target.closest('[data-face]');if(!u)return; + if(u.dataset.ownerApp&&!u.classList.contains('locate-onpane'))return; + const owner=u.dataset.ownerApp||defaultOwner; + if(owner==='@ui')flashUi(u.dataset.face);else flashPkg(u.dataset.face); +} function flashEl(el){if(!el)return;el.scrollIntoView({block:'nearest',inline:'nearest',behavior:'smooth'});el.classList.remove('flashtok');void el.offsetWidth;el.classList.add('flashtok');} // Flash every matching element but scroll only the first into view, so a face // that maps to several preview spans still lands the viewport on the first. @@ -2322,6 +2512,7 @@ function uiCss(o,fgv,bgv,opts={}){const fg=fgv===undefined?effFg(o.fg):fgv,bg=bg function syncMockHeight(){const t=document.getElementById('uitable'),m=document.getElementById('mockframe');if(!t||!m)return;const lb=m.previousElementSibling,lbh=lb?lb.getBoundingClientRect().height+10:30;m.style.height=Math.max(t.getBoundingClientRect().height-lbh,220)+'px';} function buildMockFrame(){ const fr=document.getElementById('mockframe');if(!fr)return; + rebuildLocateRegistry(); const bg=MAP['bg'],fg=MAP['p']; const ln=uf('line-number'),lnc=uf('line-number-current-line'),hl=uf('hl-line'),hil=uf('highlight'),reg=uf('region'),isr=uf('isearch'),isf=uf('isearch-fail'),laz=uf('lazy-highlight'),par=uf('show-paren-match'),parx=uf('show-paren-mismatch'),cur=uf('cursor'),ml=uf('mode-line'),mli=uf('mode-line-inactive'),mlh=uf('mode-line-highlight'),mb=uf('minibuffer-prompt'),frng=uf('fringe'),vb=uf('vertical-border'),lnk=uf('link'),err=uf('error'),wrn=uf('warning'),suc=uf('success'); const lines=[ @@ -2390,7 +2581,7 @@ function buildMockFrame(){ html+=`
I-search: count zzz [no match]
`; html+=`
https://gnu.org error warning ok
`; fr.innerHTML=html;fr.style.background=bg;fr.style.color=fg; - fr.onclick=(e)=>{const u=e.target.closest('[data-face]');if(u){flashUi(u.dataset.face);return;}const k=e.target.closest('[data-k]');if(k)flashAssign(k.dataset.k);}; + fr.onclick=(e)=>{if(e.target.closest('[data-face]')){locateClick(e,'@ui');return;}const k=e.target.closest('[data-k]');if(k)flashAssign(k.dataset.k);}; } // All three tiers share one dropdown — the swatch div from mkColorDropdown. The // native