region:focus / region:blur — focused-region indicator

Walkthrough

1. 1

   Subscribe via raw strings — these events lack `Builder.EVENTS.*` constants

   Like history:change (see events/3-history-change), region:focus and region:blur fire reliably from PaddingMarginControl.js but have NO entries in Builder.EVENTS. Subscribe via raw strings — same swap-when-the-constant-lands path applies.

   Both events emit on the builder.events bus. Payload shape: { elementUid, namespace, regionKey }. The regionKey is one of padding-top, padding-right, padding-bottom, padding-left — the 4 sides of the padding control. Same shape applies to margin controls when those use the same primitive.

   JavaScript Copy

   // Two listeners — symmetrical pair, same payload shape.
   builder.events.on('region:focus', ({ elementUid, regionKey }) => {
     const strip = document.getElementById('c5RegionStrip');
     strip.dataset.region = regionKey;             // 'padding-top' etc.
     strip.textContent    = `Editing: ${regionKey} (#${elementUid})`;
   });
   
   builder.events.on('region:blur', ({ regionKey }) => {
     const strip = document.getElementById('c5RegionStrip');
     // Only clear if the blurred region matches what's currently shown —
     // a fast Tab between sides fires blur(top) THEN focus(right) and
     // we don't want the blur to clear the freshly-shown right region.
     if (strip.dataset.region === regionKey) {
       strip.dataset.region = '';
       strip.textContent    = '';
     }
   });

2. 2

   Why "region" and not "hover" — the events fire from a control, not the canvas

   The W6 plan originally called this a "currently hovering" status strip — but the events do NOT fire on canvas hover. They fire when the buyer FOCUSES one of the four padding-side <input>s in the settings panel's padding control. That's a much more specific signal than "hover" but a much more useful one — focus implies intent (the buyer is about to type a number), hover only implies attention.

   Use cases that earn this event: (1) scoped autosave — debounce per-region instead of per-document so a typing burst on padding-top doesn't collide with one on padding-right; (2) active-region indicator — show the buyer which side they're editing on a tablet where the input field might be off-screen; (3) undo-grouping — group all changes to the same region into a single undo entry. The HistoryManager already does (3) internally — see src/includes/HistoryManager.js "region:focus" subscription for the canonical pattern.

   JavaScript Copy

   // Engine-internal pattern (HistoryManager.js): coalesce region edits
   // into one undo entry. Your code can do the same for autosave scoping.
   let activeRegion = null;
   builder.events.on('region:focus', ({ regionKey }) => {
     activeRegion = regionKey;
   });
   builder.events.on('region:blur', () => {
     activeRegion = null;
   });
   
   // Inside your document:changed listener:
   builder.events.on(Builder.EVENTS.DOCUMENT_CHANGED, () => {
     // Use the active region as the autosave bucket key —
     // a typing burst on padding-top stays scoped to that bucket
     // even if the buyer Tabs to padding-right mid-burst.
     scheduleAutosave(activeRegion ?? 'global');
   });

3. 3

   Empty state + Tab handling — the strip should always read as "ready"

   The strip reads empty when no region is focused. CSS-only empty state via :empty::before with a placeholder ("Click a padding side in the settings panel below"). This matches the cookbook 5-sidebar-only floating-panel pattern (D13.C.B.5) — empty surfaces in event-driven UI must read as "ready" not "broken."

   Tab between sides fires region:blur(currentSide) → region:focus(nextSide) in rapid succession. Without the "only-clear-if-matches" guard in Step 1, the blur handler would wipe the strip just before the focus handler re-paints it — and depending on browser microtask order the strip would flicker or stay empty entirely. The guard makes the transition seamless.

   CSS Copy

   .c5-region-strip {
     font-size: 11px;
     padding: 3px 12px;
     border-radius: 999px;
     background: var(--demo-bg-elevated, #f3f4f6);
     color: var(--demo-text-secondary, #4b5563);
     transition: background 240ms ease, color 240ms ease;
     min-height: 18px;
   }
   .c5-region-strip:empty::before {
     content: 'Click a padding side in the settings panel below.';
     color: var(--demo-text-muted, #9ca3af);
     font-style: italic;
   }
   .c5-region-strip[data-region^="padding-"] {
     background: var(--demo-accent-soft, #e0e7ff);
     color: var(--demo-accent, #4338ca);
   }