DOM

The DOM adapter projects energy state onto an element as a data-energy-level attribute plus CSS custom properties. Any framework - or plain HTML and CSS - can react to it. Import from @kumbatio/energy-system/dom.

Apply a level

import { applyEnergyLevel } from '@kumbatio/energy-system/dom'

applyEnergyLevel(50)

This sets, on document.body (or a root you pass):

• data-energy-level="50"
• --energy-chrome-opacity, --energy-chrome-opacity-hover
• --energy-content-max-width, --energy-content-font-scale

The variable values come from uiVisibilityStrategy, so the JS and CSS-only paths always agree.

// Scope to a specific element instead of body
applyEnergyLevel(25, document.querySelector<HTMLElement>('#workspace')!)

An invalid level throws; outside a browser you must pass an explicit root.

Read the current level

import { readEnergyLevel } from '@kumbatio/energy-system/dom'

const level = readEnergyLevel() // EnergyLevel; 100 when nothing valid is set

Observe changes

observeEnergyLevel watches the attribute with a MutationObserver and calls back with (state, prev):

import { observeEnergyLevel } from '@kumbatio/energy-system/dom'

const cleanup = observeEnergyLevel((state, prev) => {
  console.log(`Energy: ${prev.level} -> ${state.level}`)
})

// later
cleanup()

Wiring the engine to the DOM

Bridge the core engine to the DOM in one subscription:

import { createEnergyEngine } from '@kumbatio/energy-system'
import { applyEnergyLevel } from '@kumbatio/energy-system/dom'

const engine = createEnergyEngine({ initialLevel: 75 })

applyEnergyLevel(engine.getState().level)
engine.subscribe((state) => {
  applyEnergyLevel(state.level)
})

In React, <EnergyProvider applyToDOM> does exactly this for you.

Data attributes at a glance

The min/max/presence attributes are handled by the reference stylesheet - see the CSS quickstart.

Full DOM reference: /docs/api/dom.