Presence

Declare which energy levels a UI element belongs to - defineEnergyPresence, presenceAtOrAbove, presenceAtOrBelow, createPresenceStrategy

Presence annotation maps every EnergyLevel to an EnergyPresence ('visible' | 'muted' | 'hidden'). The React counterpart is EnergyGate / useEnergyPresence; the CSS-only counterpart is the data-energy-min / data-energy-max attributes.

EnergyPresenceSpec

type EnergyPresenceSpec = Partial<Record<EnergyLevel, EnergyPresence>> & {
  default?: EnergyPresence
}

Per-level presence spec. Unlisted levels fall back to default ('visible' when omitted).

defineEnergyPresence

function defineEnergyPresence(spec?: EnergyPresenceSpec): EnergyPresenceMap

Build a complete, frozen presence map from a partial spec. Throws for invalid presence values (in default or any level entry).

import { defineEnergyPresence } from '@kumbatio/energy-system'

// Hide the AI chat at 50 and below, keep it muted at 75:
const aiChatPresence = defineEnergyPresence({
  default: 'visible',
  75: 'muted',
  50: 'hidden',
  25: 'hidden',
  0: 'hidden',
})

presenceAtOrAbove

function presenceAtOrAbove(min: EnergyLevel, below?: EnergyPresence): EnergyPresenceMap

Presence map for elements that need at least min energy. At min and above the element is visible; below min it is below (default 'hidden'). Throws for an invalid level or presence.

const composerToolbar = presenceAtOrAbove(50)    // hidden at 25 and 0
const aiSidebar = presenceAtOrAbove(75, 'muted') // muted below 75

presenceAtOrBelow

function presenceAtOrBelow(max: EnergyLevel, above?: EnergyPresence): EnergyPresenceMap

Presence map for elements that only belong at low energy - recovery hints, "one thing at a time" affordances. At max and below the element is visible; above max it is above (default 'hidden'). Throws for an invalid level or presence.

resolveEnergyPresence

function resolveEnergyPresence(presence: EnergyPresenceMap, level: EnergyLevel): EnergyPresence

Resolve the presence of an element for a given energy level. Throws for an invalid level, or when the map has no valid entry for it.

isPresenceVisible

function isPresenceVisible(presence: EnergyPresence): boolean

Returns true unless the presence is 'hidden' (i.e. 'muted' counts as visible).

isEnergyPresence

function isEnergyPresence(value: unknown): value is EnergyPresence

Validate that an unknown value is a valid EnergyPresence.

createPresenceStrategy

function createPresenceStrategy(
  name: string,
  presence: EnergyPresenceMap,
): AdaptationStrategy<EnergyPresence>

Lift a presence map into an AdaptationStrategy so it can be resolved through the engine like any built-in strategy. The full map is validated once at creation, so the returned resolve() can never fail. Throws for an empty/non-string name or an incomplete map.

import { createEnergyEngine, createPresenceStrategy, presenceAtOrAbove } from '@kumbatio/energy-system'

const engine = createEnergyEngine()
const aiChat = createPresenceStrategy('ai-chat', presenceAtOrAbove(75))
engine.resolve(aiChat) // 'visible' | 'muted' | 'hidden'

Presence

On this page