WORK-724
ID:WORK-724Status:done

Behaviours write state as data-state, not as classes on rune-owned elements

SPEC-196 D6. Four behaviours write classes onto elements a rune owns. Under a theme that chooses classes: "none", that would put classes back on the page, and under a mapping table it produces junk:

Priority:mediumComplexity:simpleMilestone:v0.50.0Source:SPEC-196
claude/rune-composition-layout-convention-hkqrzx View source

Criteria completion

Criteria completion: 7 of 7 (100%) checked; history from Nov 9 to Nov 120%25%50%75%100%Nov 9Nov 12
Branches 2
claude/rune-composition-layout-convention-hkqrzx current done
claude/composition-usage-rune-pages-c87ar6 readymain ready
History 2
  1. 2343cdf
    • ☑ `reveal` sets `data-state` on each step and writes no class on it
    • ☑ `tabs` sets `data-state` on the active tab and panel, writes no class, and no longer reads a class from another element
    • ☑ The audio player sets `data-state` on the active track and writes no class on it
    • ☑ `copy` sets `data-state` for its copied state and writes no class on a rune-owned element
    • ☑ The Lumina rules for those states select `[data-state="…"]`
    • ☑ The behaviour tests for `reveal`, `tabs` and `copy` assert the attribute, and the audio player gains a test that does
    • ☑ A test fails when a behaviour calls `classList.add`, `classList.toggle` or assigns `className` on an element it did not create
    by bjornolofandersson
  2. 59607e7
    Created (ready)by bjornolofandersson

Acceptance Criteria

  • reveal sets data-state on each step and writes no class on it
  • tabs sets data-state on the active tab and panel, writes no class, and no longer reads a class from another element
  • The audio player sets data-state on the active track and writes no class on it
  • copy sets data-state for its copied state and writes no class on a rune-owned element
  • The Lumina rules for those states select [data-state="…"]
  • The behaviour tests for reveal, tabs and copy assert the attribute, and the audio player gains a test that does
  • A test fails when a behaviour calls classList.add, classList.toggle or assigns className on an element it did not create

Approach

  • Check each behaviour for an existing data-state (or aria-selected, aria-current) before adding one. Where ARIA already says the state, the CSS can select ARIA and no new attribute is needed.
  • State values follow what exists: active / inactive, visible / hidden, copied.
  • The last criterion's test can be narrow: it flags class writes on elements reached through a query, not on elements made with createElement in the same function. Behaviour-built UI is WORK-725.

References

  • SPEC-196 D6.
  • ADR-048: implementation order, step 1.

Resolution

Completed: 2026-11-12

Branch: claude/rune-composition-layout-convention-hkqrzx

What was done

  • reveal.ts: steps carry only data-state="open"|"closed" (already set); the root gets data-enhanced while the behaviour runs; cleanup restores closed and removes the marker. Lumina and skeleton reveal.css hide :where(.rf-reveal[data-enhanced]) .rf-reveal-step:where([data-state="closed"]) and show [data-state="open"].
  • tabs.ts: no longer derives an --active class from the first button's class; data-state only. CSS: tabs.css, codegroup.css, milestone.css (the three blocks whose tabs the behaviour drives) select [data-state="active"].
  • elements/audio.ts: playlist tracks and chapter buttons get data-state="active"|"inactive"; disconnect clears the tracks' state. audio.css follows.
  • copy.ts: data-state="copied" on its button; code.css follows.
  • drawer.ts: html[data-drawer-open] instead of html.rf-drawer-open (the root is not an element the behaviour created, so the guard counts it); skeleton drawer.css follows.
  • Every retargeted rule wraps the attribute in :where(), so specificity is unchanged.
  • Tests: reveal, tabs and copy tests assert the attribute and that no class changed; new packages/behaviors/test/audio.test.ts drives a real <rf-audio> against a playlist; the class-write guard is in no-class-reads.test.ts.

Notes

  • The reveal trap: the server output marks every step data-state="closed" (RevealStep.rootAttributes). Mapping the hidden style to [data-state="closed"] alone would have hidden every step on a page without JavaScript, or before it loads. data-enhanced scopes the rule to a reveal the behaviour is running; no existing "enhanced" marker convention was found to reuse.
  • Chapter buttons are behaviour-built, but they are reached through a query, so the guard could not tell them from rune-owned elements; moving them to data-state was cheaper than an exception.
  • Beyond the four named runes, drawer's page lock was the only other class write on an element a behaviour did not create (plus a script string written into a sandbox iframe's own document, allowlisted in the guard).