Appearance

component-lifecycle

component-lifecycle / Component

Abstract Class: Component<P, TEventMap, TOptions> ​

Abstract class representing a component in a web application.

Type Parameters ​

P ​

P extends string = "component"

The prefix used for event names. Default: "component".

TEventMap ​

TEventMap extends BaseEventMap<P> = BaseEventMap<P>

The type of the event map. Default: BaseEventMap.

TOptions ​

TOptions extends ComponentOptions = ComponentOptions

The type of the options object. Default: ComponentOptions.

Constructors ​

Constructor ​

new Component<P, TEventMap, TOptions>(element, options?): Component<P, TEventMap, TOptions>

Constructor for Component.

Parameters ​

element ​

HTMLElement

The DOM element this component is attached to.

options? ​

Partial<TOptions>

Optional configuration object.

Returns ​

Component<P, TEventMap, TOptions>

Properties ​

element ​

readonly element: HTMLElement

The DOM element this component is attached to.

options ​

protected readonly options: TOptions

PREFIX ​

abstract protected readonly PREFIX: P

Accessors ​

state ​

Get Signature ​

get state(): LifecycleState

Returns the current lifecycle state of this component.

Returns ​

LifecycleState

The current lifecycle state of this component.

Methods ​

attach() ​

attach(): Promise<void>

Attaches the component to the DOM.

Transitions the component to the attached lifecycle state. Implementation notes:

  • This method should not be overridden by subclasses. To perform additional attachment tasks, override the doAttach() method.
  • This method should be called when the component is ready to be attached.

Returns ​

Promise<void>

A promise that resolves when the attachment is complete.

Remarks ​

Fires:

  • attached If the component transitions to the attached lifecycle state.
  • transition-cancelled If the transition is cancelled by a lifecycle hook.
  • transition-invalid If the transition is structurally invalid (invalid lifecycle state graph).

canTransition() ​

protected canTransition(next): boolean

Checks whether a transition to the given lifecycle state is valid.

Transition is valid if the current lifecycle state is included in the array of valid transitions for the given lifecycle state.

Parameters ​

next ​

LifecycleState

The lifecycle state to transition to.

Returns ​

boolean

Whether the transition is valid.

destroy() ​

destroy(): Promise<void>

Destroys the component.

Transitions the component to the destroyed lifecycle state. Implementation notes:

  • This method should not be overridden by subclasses. To perform additional destruction tasks, override the doDestroy() method.
  • This method should be called when the component is ready to be destroyed.

Returns ​

Promise<void>

A promise that resolves when the destruction is complete.

Remarks ​

Fires:

  • destroyed If the component transitions to the destroyed lifecycle state.
  • transition-cancelled If the transition is cancelled by a lifecycle hook.
  • transition-invalid If the transition is structurally invalid (invalid lifecycle state graph).

dispose() ​

dispose(): Promise<void>

Disposes the component.

Transitions the component to the disposed lifecycle state. Implementation notes:

  • This method should not be overridden by subclasses. To perform additional disposal tasks, override the doDispose() method.
  • This method should be called when the component is ready to be disposed.

Returns ​

Promise<void>

A promise that resolves when the disposal is complete.

Remarks ​

Fires:

  • disposed If the component transitions to the disposed lifecycle state.
  • transition-cancelled If the transition is cancelled by a lifecycle hook.
  • transition-invalid If the transition is structurally invalid (invalid lifecycle state graph).

doAttach() ​

protected doAttach(): Promise<{ cancelled: boolean; reason?: string; }>

Hooks that are called when the component transitions to the attached lifecycle state.

Implementation notes:

  • Can be overridden by subclasses to perform additional attachment tasks.
  • If async operations are needed, return a promise that resolves when complete.
  • Return { cancelled: true, reason: "..." } to prevent the transition.

Returns ​

Promise<{ cancelled: boolean; reason?: string; }>

A promise that resolves to an object with cancelled flag and optional reason.

doDestroy() ​

protected doDestroy(): Promise<{ cancelled: boolean; reason?: string; }>

Hooks that are called when the component transitions to the destroyed lifecycle state.

Implementation notes:

  • Can be overridden by subclasses to perform additional destruction tasks.
  • If async operations are needed, return a promise that resolves when complete.
  • Return { cancelled: true, reason: "..." } to prevent the transition.

Returns ​

Promise<{ cancelled: boolean; reason?: string; }>

A promise that resolves to an object with cancelled flag and optional reason.

doDispose() ​

protected doDispose(): Promise<{ cancelled: boolean; reason?: string; }>

Hooks that are called when the component transitions to the disposed lifecycle state.

Implementation notes:

  • Can be overridden by subclasses to perform additional disposal tasks.
  • If async operations are needed, return a promise that resolves when complete.
  • Return { cancelled: true, reason: "..." } to prevent the transition.

Returns ​

Promise<{ cancelled: boolean; reason?: string; }>

A promise that resolves to an object with cancelled flag and optional reason.

doInit() ​

protected doInit(): Promise<{ cancelled: boolean; reason?: string; }>

Hooks that are called when the component transitions to the initialized lifecycle state.

Implementation notes:

  • Can be overridden by subclasses to perform additional initialization tasks.
  • If async operations are needed, return a promise that resolves when complete.
  • Return { cancelled: true, reason: "..." } to prevent the transition.

Returns ​

Promise<{ cancelled: boolean; reason?: string; }>

A promise that resolves to an object with cancelled flag and optional reason.

emit() ​

protected emit<K>(name, detail): void

Emits a custom event with the given name and detail.

Type Parameters ​

K ​

K extends string | number | symbol

The type of the event to be emitted.

Parameters ​

name ​

K & string

The name of the event to be emitted.

detail ​

TEventMap[K]

The detail of the event to be emitted.

Returns ​

void

Remarks ​

  • The event name will be prefixed with the component's prefix.
  • Events bubble to the document by default (bubbles: true) unless the component was instantiated with bubbleEvents: false.

init() ​

init(): Promise<void>

Initializes the component.

Transitions the component to the initialized lifecycle state. Implementation notes:

  • This method should not be overridden by subclasses. To perform additional initialization tasks, override the doInit() method.
  • This method should be called when the component is ready to be initialized.

Returns ​

Promise<void>

A promise that resolves when the initialization is complete.

Remarks ​

Fires:

  • initialized If the component transitions to the initialized lifecycle state.
  • transition-cancelled If the transition is cancelled by a lifecycle hook.
  • transition-invalid If the transition is structurally invalid (invalid lifecycle state graph).

is() ​

is(state): boolean

Checks if the component is in the given lifecycle state.

Parameters ​

state ​

LifecycleState

The lifecycle state to check against.

Returns ​

boolean

Whether the component is in the given lifecycle state.

isAttached() ​

isAttached(): boolean

Whether this component is in the attached lifecycle state.

Returns ​

boolean

Whether this component is in the attached lifecycle state.

isDestroyed() ​

isDestroyed(): boolean

Whether this component is in the destroyed lifecycle state.

Returns ​

boolean

Whether this component is in the destroyed lifecycle state.

isDisposed() ​

isDisposed(): boolean

Whether this component is in the disposed lifecycle state.

Returns ​

boolean

Whether this component is in the disposed lifecycle state.

isIdle() ​

isIdle(): boolean

Whether this component is in the idle lifecycle state.

Returns ​

boolean

Whether this component is in the idle lifecycle state.

isInitialized() ​

isInitialized(): boolean

Whether this component is in the initialized lifecycle state.

Returns ​

boolean

Whether this component is in the initialized lifecycle state.

off() ​

off<K>(name, handler): Component<P, TEventMap, TOptions>

Stops listening for the given lifecycle event.

Type Parameters ​

K ​

K extends string | number | symbol

The type of the event to stop listening for.

Parameters ​

name ​

`${P}:${K & string}`

The name of the event to stop listening for.

handler ​

(ev) => void

The handler to stop calling when the event is emitted.

Returns ​

Component<P, TEventMap, TOptions>

This component instance.

on() ​

on<K>(name, handler): Component<P, TEventMap, TOptions>

Listens for the given lifecycle event and calls the provided handler when it is emitted.

Type Parameters ​

K ​

K extends string | number | symbol

The type of the event to be listened for.

Parameters ​

name ​

`${P}:${K & string}`

The name of the event to be listened for.

handler ​

(ev) => void

The handler to be called when the event is emitted.

Returns ​

Component<P, TEventMap, TOptions>

This component instance.

once() ​

once<K>(name, handler): Component<P, TEventMap, TOptions>

Listens for the given lifecycle event and calls the provided handler when it is emitted, only once.

Type Parameters ​

K ​

K extends string | number | symbol

The type of the event to be listened for.

Parameters ​

name ​

`${P}:${K & string}`

The name of the event to be listened for.

handler ​

(ev) => void

The handler to be called when the event is emitted.

Returns ​

Component<P, TEventMap, TOptions>

This component instance.

transitionTo() ​

protected transitionTo(next): Promise<void>

Transitions the component to the given lifecycle state.

If the transition is invalid, the component remains in its current lifecycle state. Awaits the corresponding lifecycle hook before completing the transition. If the hook returns { cancelled: true }, the transition is abandoned.

Parameters ​

next ​

LifecycleState

The lifecycle state to transition to.

Returns ​

Promise<void>

A promise that resolves when the transition is complete.

Remarks ​

Fires:

  • initialized If the component transitions to the initialized lifecycle state.
  • attached If the component transitions to the attached lifecycle state.
  • disposed If the component transitions to the disposed lifecycle state.
  • destroyed If the component transitions to the destroyed lifecycle state.
  • transition-cancelled If the transition is cancelled by a lifecycle hook.
  • transition-invalid If the transition is structurally invalid (invalid lifecycle state graph).

getDefaultOptions() ​

protected static getDefaultOptions(): ComponentOptions

Returns the default options for this component class.

Returns ​

ComponentOptions

The default options configuration

Remarks ​

Subclasses should override this method if they add custom options. Always call super.getDefaultOptions() and spread the result.

Example ​

typescript
type CustomOptions = ExtendableComponentOptions<{ customOption: string }>;
export  class CustomOptionsComponent extends Component<
    "custom-options",
    LifecycleEventMap<"custom-options">,
    CustomOptions> {
    protected readonly PREFIX = "custom-options";
    
    protected static getDefaultOptions(): CustomOptions {
        return {
            ...super.getDefaultOptions(),
            customOption: "custom value"
        };
    }
}