diff options
| -rw-r--r-- | docs/prototypes/README.org | 59 | ||||
| -rw-r--r-- | todo.org | 4 |
2 files changed, 58 insertions, 5 deletions
diff --git a/docs/prototypes/README.org b/docs/prototypes/README.org index 674a45d..651636a 100644 --- a/docs/prototypes/README.org +++ b/docs/prototypes/README.org @@ -18,7 +18,62 @@ point at. - [[file:panel-widget-gallery.html][panel-widget-gallery.html]] — the shared instrument-console widget kit (lamps, engraved sections, console keys, needle gauges). The living catalogue: every widget here is the visual + behavioral spec for - its reusable-component ports. + its reusable-component ports. All widgets build from [[file:widgets.js][widgets.js]] (below); + the gallery page is the reference consumer. +- [[file:2026-07-03-waybar-redesign-prototype.html][2026-07-03-waybar-redesign-prototype.html]] — three directions for sprucing up + waybar in the dupre instrument-console aesthetic (future work). + +* Widget library ([[file:widgets.js][widgets.js]]) + +The whole kit lives in =widgets.js= — a classic script (no modules, no build +step) exposing the =GW= namespace with one builder per gallery card. Load it +with =<script src="widgets.js"></script>= and call builders directly. + +** Builder contract + +=GW.name(host, opts)= → handle ={el, get, set, ...}=. =host= is an empty +element the widget renders into. =opts.onChange(value, text)= fires on every +state change, including the initial paint; =text= is the widget's canonical +readout string. (Exception: live meters whose original init was silent — they +paint on the first =set=/=push=.) + +** Styling + +Widget-internal CSS ships inside =widgets.js= (the =GW_CSS= block, injected +once as =<style id="gw-css">= at load), so widgets are fully styled on any +page. The design tokens (=--gold=, =--glow-hi=, the amber family, =--mono=, +=--pulse-rate=, …) must be defined on =:root= by the consumer — the gallery's +generated =:root= block is the reference; =tokens.json= is the source. + +** Tick contract (live meters) + +The page owns the clock and the signal source; builders own rendering state. +Live meters expose value-driven handles that repaint synchronously and fire +=onChange=: + +- =set(level)= for level meters (peak-hold logic lives in the builder) +- =push(v)= / =set(samples, current)= for history meters (the builder owns + the ring buffer) +- =set(samples, amp)= for sampled traces (samples normalized) + +Widget-owned animation (the R17 scope trace, R31 radar sweep, R44 servo +chase, R52 pseudo-PC, R53 day clock, R10 TIME page) runs inside the builder, +gated on =prefers-reduced-motion=. + +** Style options + +Widgets with named style axes take them as constructor opts backed by a +=STYLES= table on the builder — e.g. =GW.slideToggle(host, {onStyle:'green', +thumb:'brass'})= with the axes enumerated in =GW.slideToggle.STYLES=, and +=handle.setStyle(axis, name)= to restyle a live instance. The gallery's +option chips are demo rigs driving =setStyle=. + +** Verification + +=tests/gallery-probes/= drives the full kit headlessly over CDP: +=probe.mjs= (every card renders + responds, size toggle, drags at zoom) and +=probe-fams.mjs= (screen-family retinting). Run with =node= against the +gallery file URL; both must pass before a gallery or widgets.js change lands. * Design tokens (single source, three targets) @@ -35,5 +90,3 @@ gallery card 10) — it reads gallery-tokens.el and emits the widget as SVG via svg.el, so the same look renders inside Emacs. Tests: =tests/gallery-tokens/= (generator, unittest) and =tests/gallery-widgets/= (renderer, ERT), both in =make test-unit=. -- [[file:2026-07-03-waybar-redesign-prototype.html][2026-07-03-waybar-redesign-prototype.html]] — three directions for sprucing up - waybar in the dupre instrument-console aesthetic (future work). @@ -76,8 +76,8 @@ Build runs per the [[file:docs/specs/2026-07-12-component-generation-spec.org][c Craig approved with the componentization go-ahead (option 1): =widgets.js= as a classic script exposing one =GW= namespace, relative =<script src>= so =file://= keeps working, shared helpers inside, framework wrappers vNext. Decision flipped DONE in the spec (cookie 8/8). Gate per the same approval: extraction proceeds ungated (lossless transform); the validation lamps gate only per-widget Emacs ports and the final blessing. *** 2026-07-12 Sun @ 20:57:50 -0500 Spec reviewed and decomposed (DRAFT → READY → DOING) spec-review passed (Ready): 3 findings, all accepted and folded same pass — option-1 supersession of the demand-gated extraction order (Phases 1-2 swapped: extraction first, ungated), the card-record refactor named in Phase 1, stale counts refreshed (109 cards / R56). Probe baseline repaired first (753380e — two stale assertions from the evening sprint). Phase tasks below; =:SPEC_ID:= stamped on this parent. -*** TODO Phase 1 — web library extraction :refactor:solo: -Lift all 109 card builders into =docs/prototypes/widgets.js= (classic script, =GW= namespace, shared engine inside: svgEl/polar/vuDb/dragX/dragY/dragDelta/seg7/SCREEN_FAMS/gradients); restructure each card as a declarative record (no/title/stage/options/readout/note/spec-sheet incl ref/lamp) rendered by one =card()= path. Batches of ~10-15; per-batch gate = green =tests/gallery-probes/probe.mjs= + =probe-fams.mjs=; commit+push per batch. Gallery stays working from =file://= throughout. Close with the slide toggle (card 01) as the first fully-realized component: its four option groups become constructor args (on/off/offText/thumb). +*** 2026-07-12 Sun @ 22:56:40 -0500 Phase 1 complete — all 109 widgets extracted into widgets.js +All 109 card builders lifted into [[file:docs/prototypes/widgets.js][docs/prototypes/widgets.js]] (classic script, =GW= namespace, shared engine: svgEl/polar/vuDb/drag helpers/seg7/SCREEN_FAMS/gradient defs); every card is now a declarative record rendered by one =card()= path, all wiring blocks deleted. Widget CSS (incl. pulse/flipdrop/reelspin keyframes) moved from the gallery =<style>= block into =GW_CSS=, injected by widgets.js — verified pixel-identical under forced reduced motion (masked live-date cards N26/R35). Tick contract settled: the page owns the clock + demo signal; live meters expose value-driven handles; widget-owned animation lives in builders behind reduced-motion gates. Finale: slide toggle (card 01) is the first fully-realized component — its four option groups are =GW.slideToggle= constructor opts backed by =STYLES=, the gallery chips a demo rig on =handle.setStyle=. README consumers section documents the GW API + tick contract. Per-batch gate stayed green throughout (probe.mjs, probe-fams.mjs, a 239-check behavioral suite, reduced-motion smoke). Commits acee657 → 7b3bc47 (18 batches), all pushed. *** TODO Phase 2 — demand inventory (Emacs/waybar) :design: Widget-to-target matrix for the scripted-port targets: walk the live waybar panels (net/bt/audio/maint) and the Emacs surfaces Craig names; record which cards each actually wants. Lands in the spec's appendix; Craig approves. Tree untouched. Not =:solo:= — the matrix is his call. *** TODO Phase 3 — Emacs ports of demanded widgets :feature: |