React

import { EnergyGate, EnergyIndicator, EnergyProvider } from '@kumbatio/energy-system/react'

export declare function EnergyGate({ presence, min, max, fallback, whenHidden, children, }: EnergyGateProps): ReactNode;

// Hide the AI chat at 50 and below:
<EnergyGate min={75}>
  <AiChatPanel />
</EnergyGate>

// Full presence map, muted state styled by the child:
<EnergyGate presence={aiChatPresence}>
  {(presence) => <AiChatPanel muted={presence === 'muted'} />}
</EnergyGate>

export declare function EnergyIndicator({ children }: EnergyIndicatorProps): ReactNode;

export declare function EnergyProvider({ engine: externalEngine, defaultLevel, persistence, onLevelChange, applyToDOM, domTarget, children, }: EnergyProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<EnergyEngine | null>>;

export declare function useEnergyGate(minLevel: EnergyLevel): boolean;

export declare function useEnergyLevel(): [
    EnergyLevel,
    (level: EnergyLevel, source?: EnergySource) => void
];

export declare function useEnergyLevelCycler(): () => void;

export declare function useEnergyPresence(presence: EnergyPresenceMap): EnergyPresence;

export declare function useEnergyState(): EnergyState;

export declare function useStrategy<T>(strategy: AdaptationStrategy<T>): T;

export interface EnergyIndicatorProps {
    children: (props: EnergyIndicatorRenderProps) => ReactNode;
}

export interface EnergyIndicatorRenderProps {
    level: EnergyLevel;
    label: string;
    description: string;
    cognitiveProfile: EnergyLevelDefinition['cognitiveProfile'];
    state: EnergyState;
    definition: EnergyLevelDefinition;
    levels: readonly EnergyLevelDefinition[];
    cycle: () => void;
    setLevel: (level: EnergyLevel, source?: EnergySource) => void;
}

export interface EnergyProviderProps {
    /** Pre-created engine. When provided, this engine is used directly. */
    engine?: EnergyEngine;
    /** Initial energy level when the provider creates its own engine. */
    defaultLevel?: EnergyLevel;
    /** Persistence adapter when the provider creates its own engine. */
    persistence?: EnergyPersistence;
    /** Called on every level change. */
    onLevelChange?: EnergyChangeListener;
    /** Whether to apply energy level to DOM via data attributes */
    applyToDOM?: boolean;
    /**
     * Element the level is projected onto. Default: `document.body`.
     *
     * Pass `() => document.documentElement` when the stylesheet keys off
     * `[data-energy-level]` at the root - resolved inside the effect, so the
     * render phase never touches the DOM. Whatever the target, the provider
     * snapshots what was there, layers overlapping providers, and restores the
     * baseline on unmount.
     */
    domTarget?: HTMLElement | (() => HTMLElement | null);
    children: ReactNode;
}

export type EnergyGateProps = EnergyGateBaseProps & ({
    /** Full presence declaration for this element */
    presence: EnergyPresenceMap;
    min?: never;
    max?: never;
} | {
    presence?: never;
    /** Shorthand: visible at or above this level, hidden below */
    min: EnergyLevel;
    /** Optionally also hidden above this level (band gating) */
    max?: EnergyLevel;
} | {
    presence?: never;
    min?: never;
    /** Shorthand: visible at or below this level, hidden above */
    max: EnergyLevel;
});

export type EnergyHiddenBehavior = 'preserve' | 'unmount';