import { type DOMAttributeValue, type OptionalAndComplete, type Reference } from "@knyt/artisan";
import { type StyleSheet } from "@knyt/tailor";
import { __hostAdapter, __lifecycle, ControllableAdapter, EventListenerController, EventListenerManager, LifecycleAdapter, StyleSheetAdoptionAdapter, type Controllable, type Effect, type EventListenableObserver, type Lifecycle, type LifecycleDelegateHost, type ReactiveControllerHost } from "@knyt/tasker";
import { __resourceRenderers, BasicResourceRendererHost, RenderMode, type RenderOptions, type RenderResult, type ResourceRenderer, type ResourceRendererHost, type UpdateOptions } from "@knyt/weaver";
import { defer } from "./DeferredContent/defer";
import type { PromiseReference } from "./DeferredContent/PromiseReference";
import { type HtmxObject } from "./HtmxIntegration";
import { __reactiveAdapter, ReactiveUpdateMode, type Reactive, type ReactiveAdapter } from "./Reactive";
import type { PropertiesDefinition } from "./types";
/**
 * @alpha
 */
export type KnytElementOptions = {
    /**
     * Specifies how the element should be rendered by an external renderer.
     *
     * @see {@link https://knyt.dev/s/render-modes}
     *
     * @remarks
     *
     * There are two render modes: opaque and transparent.
     *
     * In opaque mode, the element fully manages the rendering of its children,
     * and external renderers should not modify its contents.
     *
     * In transparent mode, the element allows its children to be rendered
     * or managed by an external renderer.
     *
     * @defaultValue `"transparent"`
     */
    renderMode?: `${RenderMode}`;
    /**
     * Specifies whether the element should use a shadow root, and provides options if enabled.
     *
     * If `false`, the element will not have a shadow root.
     * If a `ShadowRootInit` object is provided, a shadow root will be attached using those options.
     *
     * @defaultValue `{ mode: "closed" }`
     */
    shadowRoot?: false | ShadowRootInit;
    /**
     * Determines how the element is updated.
     *
     * @defaultValue `"reactive"`
     */
    updateMode?: `${ReactiveUpdateMode}`;
    /**
     * Controls whether adopted stylesheets are included during server-side rendering.
     *
     * @remarks
     *
     * When enabled, adopted style sheets will not be rendered as <style> elements in the server-side output.
     * By default, each adopted style sheet is rendered as a <style> element for every instance of the element,
     * which can result in a large number of style tags in the generated HTML.
     *
     * Use this option if you want to prevent all adopted style sheets adopted by the element from being rendered
     * server-side. To selectively exclude a specific style sheet from SSR, use the `disableSSR` option on the
     * style sheet itself.
     *
     * @see {@link StyleSheet}
     *
     * @defaultValue `false`
     */
    disableStylesheetSSR?: boolean;
    /**
     * Threshold for appending children in chunks.
     *
     * @remarks
     *
     * If the number of children exceeds this threshold, they are appended in chunks
     * using `requestAnimationFrame` to prevent blocking the main thread.
     *
     * @see {@link UpdateOptions.appendChunkSize}
     *
     * @alpha This is an experimental API and WILL change in the future without notice.
     */
    appendChunkSize?: UpdateOptions["appendChunkSize"];
    /**
     * When enabled, the element's shadow root will be processed by htmx.
     *
     * @remarks
     *
     * For this to work, `htmx` must be either available globally,
     * or passed as an option to the element.
     *
     * @see {@link https://htmx.org/examples/web-components/}
     *
     * @defaultValue `false`
     */
    htmx?: boolean | HtmxObject.Compat;
    /**
     * Determines whether the element is a "Container" element.
     *
     * @remarks
     *
     * A container element is defined as one that does not have a shadow root and uses
     * transparent rendering mode. In this mode, the element itself does not render its
     * own children; instead, its children are rendered by an external renderer (Weaver).
     * Without a shadow root, the element's content appears in the light DOM. Together,
     * these conditions mean the element acts purely as a container for its children,
     * delegating rendering responsibility externally.
     *
     * When container mode is enabled, these properties are configured automatically:
     *
     * - `renderMode` is set to `transparent`
     * - `shadowRoot` is set to `false`
     * - `updateMode` is set to `manual`
     * - `disableStylesheetSSR` is set to `true`
     * - `htmx` is set to `false`
     *
     * If the element is created using the `define.element` function, the default `styleSheet`
     * will set `display` to `contents`. This ensures the container does not introduce a new
     * block formatting context or disrupt the layout of its children.
     *
     * @defaultValue `false`
     */
    container?: boolean;
    /**
     * Enables debug mode for the element.
     *
     * @defaultValue `false`
     */
    debug?: boolean;
};
/**
 * This is an experimental API and will change in the future.
 *
 * @internal scope: package
 */
export type ObservedProperties<T, P extends keyof T> = Reference.SubscriberRetaining<{
    [K in P]: T[K];
}>;
declare const __isKnytElement: unique symbol;
/**
 * This symbol is used to access the post-construction logic of the `KnytElement`.
 *
 * @internal scope: workspace
 */
export declare const __postConstruct: unique symbol;
/**
 * This symbol is used to access the style sheet adoption controller of the `KnytElement`.
 *
 * @internal scope: workspace
 */
export declare const __styleSheetAdoption: unique symbol;
/**
 * The base class for all Knyt elements.
 *
 * @remarks
 *
 * This class is a mixin of the `Reactive` and `Controllable` mixins.
 * It provides a set of properties and methods that are common to all Knyt elements.
 *
 * @public
 */
export declare abstract class KnytElement extends HTMLElement implements KnytElement.Type {
    #private;
    /**
     * An adapter to implement the `ReactiveControllerHost` interface.
     *
     * @internal scope: package
     */
    [__hostAdapter]: ControllableAdapter;
    addController: ControllableAdapter["addController"];
    controlInput: ControllableAdapter["controlInput"];
    hold: ControllableAdapter["hold"];
    removeController: ControllableAdapter["removeController"];
    requestUpdate: ControllableAdapter["requestUpdate"];
    track: ControllableAdapter["track"];
    untrack: ControllableAdapter["untrack"];
    updateComplete: ControllableAdapter["updateComplete"];
    watch: ControllableAdapter["watch"];
    _getReactiveControllers: ControllableAdapter["_getReactiveControllers"];
    /** @internal scope: package */
    [__reactiveAdapter]: ReactiveAdapter;
    getProp: ReactiveAdapter<this>["getProp"];
    getProps: ReactiveAdapter<Readonly<Partial<this>>>["getProps"];
    refProp: ReactiveAdapter<this>["refProp"];
    observePropChange: ReactiveAdapter<this>["observePropChange"];
    onPropChange: ReactiveAdapter<this>["onPropChange"];
    setProp: ReactiveAdapter<this>["setProp"];
    setProps: ReactiveAdapter<this>["setProps"];
    /** @internal scope: package */
    [__lifecycle]: LifecycleAdapter<any>;
    addDelegate: LifecycleAdapter<any>["addDelegate"];
    onBeforeMount: LifecycleAdapter<any>["onBeforeMount"];
    onMounted: LifecycleAdapter<any>["onMounted"];
    onUpdateRequested: LifecycleAdapter<any>["onUpdateRequested"];
    onInterrupted: LifecycleAdapter<any>["onInterrupted"];
    onBeforeUpdate: LifecycleAdapter<any>["onBeforeUpdate"];
    onAfterUpdate: LifecycleAdapter<any>["onAfterUpdate"];
    onUnmounted: LifecycleAdapter<any>["onUnmounted"];
    onErrorCaptured: LifecycleAdapter<any>["onErrorCaptured"];
    removeDelegate: LifecycleAdapter<any>["removeDelegate"];
    /**
     * Enables debug mode for the element.
     *
     * @public
     */
    debug?: boolean;
    /**
     * Defines the reactive properties of the element
     *
     * @public
     */
    static properties: Readonly<PropertiesDefinition<any>>;
    /**
     * The default style sheet(s) adopted by the element
     *
     * @public
     */
    static styleSheet: StyleSheet<any> | undefined;
    /**
     * The observed attributes of the element.
     *
     * Do not rename. The name is standardized by the Web Components API.
     *
     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#responding_to_attribute_changes | MDN Reference}.
     *
     * @remarks
     *
     * This property is derived from the `properties` static property.
     * It returns the attribute name for each reactive element with an attribute name.
     *
     * @public
     */
    static get observedAttributes(): string[];
    /**
     * Renders the element's contents as a declaration representing the
     * element's current state.
     *
     * @public
     */
    protected render(): RenderResult;
    /**
     * Serializes the element and its contents to an HTML string.
     *
     * @remarks
     *
     * Useful for server-side rendering or generating static markup.
     *
     * Handles both open and closed shadow roots, rendering them as
     * declarative shadow roots. Adopted stylesheets may be included
     * in the output if configured.
     *
     * @public
     */
    renderToString(children: string, options?: RenderOptions): Promise<string>;
    /** @internal scope: package */
    get [__isKnytElement](): true;
    readonly [__styleSheetAdoption]: StyleSheetAdoptionAdapter;
    /**
     * Determines whether the element has focus.
     */
    hasFocus(child?: Element): boolean;
    /**
     * Creates a new instance of the `KnytElement`.
     *
     * @param options Options for configuring the element.
     *
     * @remarks
     *
     * While this constructor can accept options, elements will be created
     * by the browser the vast majority of the time, and thus options
     * will not be passed. The options are primarily useful for
     * when `KnytElement` is extended by another class that is
     * instantiated directly.
     *
     * If the element is created using the `define.element` function,
     * the options passed to that function will be used here.
     */
    constructor(options?: KnytElementOptions);
    /**
     * Called immediately after the constructor completes.
     * Use this for any initialization that must occur after the element
     * has been fully constructed.
     *
     * @remarks
     *
     * Separating this from the constructor helps ensure that
     * post-construction logic runs only after the element is fully initialized,
     * improving clarity and maintainability.
     *
     * @internal scope: workspace
     */
    [__postConstruct](): void;
    /**
     * Adopts a style sheet into the element's shadow root or light DOM.
     *
     * @remarks
     *
     * This method can accept either a `StyleSheet` instance or a URL-like
     * object with an `href` property. If a URL-like object is provided,
     * it will create a `<link>` element to load the stylesheet.
     *
     * During server-side rendering, the style sheet will be rendered as a
     * `<style>` element. When hydrating on the client, the `<style>` element
     * will be replaced with an adopted style sheet.
     * This functionality is enabled by default, but can be disabled by setting
     * `disableStylesheetSSR` to `true` in the element's options.
     */
    adoptStyleSheet(input: {
        href: string;
    } | StyleSheetAdoptionAdapter.Input): void;
    /**
     * Drops a style sheet from the element's shadow root or light DOM.
     */
    dropStyleSheet(input: StyleSheetAdoptionAdapter.Input): void;
    /**
     * A manager for event listener controllers targeting the element.
     */
    listeners: EventListenerManager<this>;
    /**
     * Adds a new event listener controller targeting the element for the given event name and listener.
     *
     * @beta This is an experimental API and may change in the future.
     */
    on<K extends string>(eventName: K, listener: EventListenableObserver.Listener<K, this>, options?: AddEventListenerOptions): EventListenerController<K, this>;
    hydrateRef(name: string): <R extends Reference<any>>(value$: R) => R;
    /**
     * Restores a state reference from serialized data.
     *
     * @remarks
     *
     * Use this to rehydrate a component's state from serialized data,
     * such as during client-side hydration after server-side rendering.
     * Hydration occurs during the first "beforeMount" lifecycle hook,
     * allowing the component to restore its state before it is mounted.
     *
     * @beta This is an experimental API and may change in the future.
     *
     * @param name - A unique name for the reference, used to identify it in the serialized data.
     * @param value$ - The reactive reference to hydrate.
     */
    hydrateRef<R extends Reference<any>>(name: string, value$: R): R;
    /**
     * Restores the value of a reactive property after SSR.
     *
     * @remarks
     *
     * During server-side rendering, reactive properties are not hydrated
     * automatically. Use this method to restore a reactive property value
     * after SSR. This runs only once, during the first "beforeMount"
     * lifecycle hook. The value may still be overridden externally, but
     * this method will not run again.
     *
     * @beta This is an experimental API and may change in the future.
     */
    hydrateProp<K extends Exclude<keyof this, symbol>>(propertyName: K): Reference.WithSubscription<this[K]>;
    /**
     * Objects that are used to render additional content in the shadow root.
     * These renderers are rendered whenever the element is updated.
     * The renderers are prepended to the shadow root.
     *
     * @internal scope: package
     */
    [__resourceRenderers]: BasicResourceRendererHost;
    /**
     * Adds a resource renderer to the element.
     *
     * @see {@link ResourceRenderer}
     */
    addRenderer(input: ResourceRenderer): void;
    /**
     * Removes a renderer from the element.
     */
    removeRenderer(input: ResourceRenderer): void;
    /**
     * Creates an effect controller and adds it to the host.
     *
     * @remarks
     *
     * Accepts a setup function, called when connected. The setup may return
     * a teardown function, which is called on disconnection.
     *
     * @returns the effect controller instance.
     */
    effect(setup: Effect.Setup<this>): Effect;
    /**
     * Signals a parent `DeferredContent` element to delay revealing its
     * content until the provided promise settles
     */
    defer<T>(promise: Promise<T>): void;
    /**
     * Signals a parent `DeferredContent` element to delay revealing its
     * content while any of the promises of the given references are unresolved.
     *
     * @remarks
     *
     * The returned `DeferredContentRenderer` instance can be used to create
     * a render function that receives the resolved values of the promises.
     * This allows rendering the content with the resolved data once all
     * promises have settled.
     */
    defer<T extends PromiseReference.Collection<any>>(...references: T): defer.Renderer<T>;
    /**
     * Handles errors that occur during lifecycle events, allowing you to manage errors gracefully
     *
     * @public
     */
    handleLifecycleError?(error: unknown): void;
    /**
     * Called after the element is connected to the DOM.
     *
     * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#lifecycle_callbacks
     *
     * @public
     */
    connectedCallback(): void;
    /**
     * Called after the element is disconnected from the DOM.
     *
     * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#lifecycle_callbacks
     *
     * @public
     */
    disconnectedCallback(): void;
    /**
     * @see https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
     *
     * @public
     */
    attributeChangedCallback(name: string, previousValue: DOMAttributeValue, nextValue: DOMAttributeValue): void;
    /**
     * Clones the element, including its reactive properties.
     *
     * @remarks
     *
     * An enhanced version of the default `cloneNode` method that
     * ensures that attribute values derived from reactive properties
     * are copied to the cloned element.
     */
    cloneNode(deep?: boolean): this;
}
export declare namespace KnytElement {
    /**
     * @internal scope: package
     */
    /**
     * ### Private Remarks
     *
     * Don't move to the `KnytElement.
     */
    type Type = HTMLElement & Controllable & Lifecycle & LifecycleDelegateHost & Reactive & ReactiveControllerHost & ResourceRendererHost & {
        [__isKnytElement]: true;
    };
    /**
     * Defines an `KnytElement` with a set of reactive properties.
     *
     * @remarks
     *
     * All properties are a union type with `undefined`, so that they
     * are required properties, but can also be set to `undefined`.
     *
     * This is necessary because reactive properties should always
     * _existI on an `KnytElement`, even if they haven't been defined.
     *
     * @alpha
     */
    type WithProps<P> = KnytElement & OptionalAndComplete<P>;
    /**
     * @internal scope: workspace
     */
    type FromPropertiesDefinition<PD extends PropertiesDefinition<any>> = KnytElement & PropertiesDefinition.ToProps<PD>;
    /**
     * Extracts the element instance type from the `ElementDefinition` of a `KnytElement`.
     */
    type FromElementDefinition<T> = T extends {
        Element: KnytElement.Constructor.Unknown;
    } ? InstanceType<T["Element"]> : never;
    interface Constructor<E extends KnytElement.Type, PD extends PropertiesDefinition<any>> {
        properties: PD;
        styleSheet: KnytElement.StaticStyleSheet;
        new (...params: any[]): E;
    }
    namespace Constructor {
        type Any = Constructor<any, any>;
        type Unknown = Constructor<KnytElement.Type, PropertiesDefinition<any>>;
        type FromElementOnly<E extends KnytElement = KnytElement> = Constructor<E, PropertiesDefinition<any>>;
        /**
         * @internal scope: workspace
         */
        type FromPropertiesDefinition<PD extends PropertiesDefinition<any>> = KnytElement.Constructor<KnytElement.FromPropertiesDefinition<PD>, PD>;
        /**
         * Extracts the properties static member from a KnytElement constructor.
         */
        type ToPropertiesDefinition<T> = T extends Constructor.Unknown ? T["properties"] : never;
    }
    /**
     * Infers the "props" from a KnytElement constructor.
     *
     * @internal scope: workspace
     */
    type ToProps<T> = T extends KnytElement.Constructor.Unknown ? PropertiesDefinition.ToProps<KnytElement.Constructor.ToPropertiesDefinition<T>> : never;
    /**
     * Extracts the attribute type from a KnytElement constructor.
     */
    type ToAttributes<T> = T extends KnytElement.Constructor.Unknown ? PropertiesDefinition.ToAttributes<KnytElement.Constructor.ToPropertiesDefinition<T>> : never;
    type StaticStyleSheet = StyleSheet<any> | StyleSheet<any>[] | undefined;
}
export declare function isKnytElement(value: unknown): value is KnytElement;
/**
 * Determines whether the element is a "Container" element,
 * from the given, unprepared options.
 *
 * @internal scope: package
 */
export declare function isContainerModeEnabled(options: KnytElementOptions): boolean;
export {};
//# sourceMappingURL=KnytElement.d.ts.map