feat: Allow @Listen and @Event decorators to accept constants/variables for event names

### Prerequisites

- [x] I have read the [Contributing Guidelines](https://github.com/stenciljs/core/blob/main/CONTRIBUTING.md).
- [x] I agree to follow the [Code of Conduct](https://github.com/stenciljs/core/blob/main/CODE_OF_CONDUCT.md).
- [x] I have searched for [existing issues](https://github.com/stenciljs/core/issues) that already include this feature request, without success.

### Describe the Feature Request

# Feature Request: Allow `@Listen` and `@Event` decorators to accept constants/variables for event names

## Problem Description

Currently, the `@Listen` decorator in Stencil only accepts string literals for event names, while the `@Event` decorator's `eventName` property has similar limitations. This prevents developers from using constants or variables consistently across both decorators, forcing duplication of event name strings throughout the codebase and increasing the risk of typos.

## Current Behavior

```typescript
const EVENTS = { CUSTOM_EVENT: 'customEvent' } as const;

// ❌ @Listen doesn't work with constants - compilation error
@Listen(EVENTS.CUSTOM_EVENT)
handleCustomEvent() { ... }

// ❌ @Event eventName doesn't work with constants in some cases
@Event({ eventName: EVENTS.CUSTOM_EVENT }) customEvent: EventEmitter; // May not work consistently

// ✅ Only string literals work reliably
@Listen('customEvent')
handleCustomEvent() { ... }

@Event({ eventName: 'customEvent' }) customEvent: EventEmitter;
```

## Desired Behavior

```typescript
const EVENTS = { CUSTOM_EVENT: 'customEvent' } as const;

// ✅ Should work - using constants consistently
@Listen(EVENTS.CUSTOM_EVENT)
handleCustomEvent() { ... }

@Event({ eventName: EVENTS.CUSTOM_EVENT }) customEvent: EventEmitter;

// ✅ Should work - using variables
const eventName = 'customEvent';
@Listen(eventName)
handleCustomEvent() { ... }

@Event({ eventName: eventName }) customEvent: EventEmitter;

// ✅ Alternative - factory function approach
@Listen(() => EVENTS.CUSTOM_EVENT)
handleCustomEvent() { ... }

@Event({ eventName: () => EVENTS.CUSTOM_EVENT }) customEvent: EventEmitter;
```

## Use Case & Motivation

**1. Avoid Typos:**
```typescript
// Current approach - prone to typos
@Event({ eventName: 'userLoginSuccess' }) loginSuccess: EventEmitter;
@Listen('userLoginSucces') // Typo! Missing 's'
handleLogin() { ... }

// Desired approach - typo-safe
const EVENTS = { USER_LOGIN_SUCCESS: 'userLoginSuccess' } as const;
@Event({ eventName: EVENTS.USER_LOGIN_SUCCESS }) loginSuccess: EventEmitter;
@Listen(EVENTS.USER_LOGIN_SUCCESS) // No typos possible
handleLogin() { ... }
```

**2. Maintain DRY Principles:**
```typescript
// Single source of truth for event names
export const EVENTS = {
  USER: {
    LOGIN_SUCCESS: 'userLoginSuccess',
    LOGIN_FAILURE: 'userLoginFailure',
    LOGOUT: 'userLogout'
  },
  DATA: {
    LOADED: 'dataLoaded',
    ERROR: 'dataError',
    REFRESH: 'dataRefresh'
  }
} as const;

// Use consistently across components
@Event({ eventName: EVENTS.USER.LOGIN_SUCCESS }) loginSuccess: EventEmitter;
@Listen(EVENTS.USER.LOGIN_SUCCESS) handleLoginSuccess() { ... }

@Event({ eventName: EVENTS.DATA.LOADED }) dataLoaded: EventEmitter;
@Listen(EVENTS.DATA.LOADED) handleDataLoaded() { ... }
```

**3. Better Refactoring:**
When event names need to change, you only update them in one place instead of searching and replacing string literals throughout the codebase.

**4. Cross-Component Consistency:**
```typescript
// Component A emits event
@Event({ eventName: EVENTS.USER.LOGIN_SUCCESS }) loginSuccess: EventEmitter;

// Component B listens to the same event
@Listen(EVENTS.USER.LOGIN_SUCCESS) handleUserLogin() { ... }

// Component C also listens
@Listen(EVENTS.USER.LOGIN_SUCCESS) onUserLogin() { ... }
```

## Proposed Solution

Allow both decorators to accept constants/variables:

**1. `@Listen` decorator:**
```typescript
const eventName = 'myEvent';
@Listen(eventName)
@Listen(EVENTS.MY_EVENT)
@Listen(() => EVENTS.MY_EVENT) // factory function alternative
```

**2. `@Event` decorator:**
```typescript
@Event({ eventName: eventName })
@Event({ eventName: EVENTS.MY_EVENT })
@Event({ eventName: () => EVENTS.MY_EVENT }) // factory function alternative
```

## Enhanced Decorator Implementation Example

```typescript
// Enhanced @Listen decorator implementation
function Listen(
  eventName: string | (() => string), 
  opts?: ListenOptions
): MethodDecorator {
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    // Resolve the event name if it's a function
    const resolvedEventName = typeof eventName === 'function' ? eventName() : eventName;
    
    // Continue with existing Stencil logic using resolvedEventName
    // (This would integrate into Stencil's existing compilation process)
    return applyListenDecorator(target, propertyKey, descriptor, resolvedEventName, opts);
  };
}

// Enhanced @Event decorator implementation  
function Event(opts: EventOptions & { eventName?: string | (() => string) }): PropertyDecorator {
  return function(target: any, propertyKey: string) {
    // Resolve the eventName if it's a function
    const resolvedOpts = { ...opts };
    if (opts.eventName && typeof opts.eventName === 'function') {
      resolvedOpts.eventName = opts.eventName();
    }
    
    // Continue with existing Stencil logic using resolvedOpts
    return applyEventDecorator(target, propertyKey, resolvedOpts);
  };
}

// Usage - no syntax changes needed, just enhanced support
const EVENTS = { 
  MODAL_CLOSED: 'modalClosed',
  USER_LOGIN: 'userLogin' 
} as const;

@Component({ tag: 'my-component' })
export class MyComponent {
  // Now works with functions that return event names
  @Event({ eventName: () => EVENTS.MODAL_CLOSED, bubbles: true })
  modalClosed: EventEmitter;
  
  @Listen(() => EVENTS.USER_LOGIN, { target: 'window' })
  handleUserLogin(event: CustomEvent) { ... }
  
  // Still works with constants/variables
  @Listen(EVENTS.MODAL_CLOSED)
  handleModalClosed() { ... }
  
  @Event({ eventName: EVENTS.USER_LOGIN })
  userLogin: EventEmitter;
  
  // Still works with string literals
  @Listen('click')
  handleClick() { ... }
  
  @Event({ eventName: 'customEvent' })
  customEvent: EventEmitter;
}
```

**Type Definitions:**
```typescript
// Updated type definitions
interface ListenOptions {
  target?: string;
  capture?: boolean;
  passive?: boolean;
}

interface EventOptions {
  eventName?: string | (() => string);
  composed?: boolean;
  cancelable?: boolean;
  bubbles?: boolean;
}

declare function Listen(
  eventName: string | (() => string), 
  opts?: ListenOptions
): MethodDecorator;

declare function Event(
  opts?: EventOptions
): PropertyDecorator;
```

This approach enhances the existing decorators to detect when a function is passed and resolve it during compilation, while maintaining backward compatibility with all existing usage patterns.

## Implementation Considerations

The Stencil compiler would need to:
1. Detect when non-string-literal values are passed to both decorators
2. Resolve the actual string value during compilation for both `@Listen` and `@Event({ eventName: ... })`
3. Handle imported constants from other modules
4. Provide helpful error messages when values can't be statically resolved
5. Ensure consistent behavior between both decorators

## Benefits

- **Type Safety:** Leverage TypeScript's type system for event names
- **DRY Principle:** Single source of truth for event names across emitters and listeners
- **Refactor Safety:** Change event names in one place, affects both emission and listening
- **IDE Support:** Better autocomplete and refactoring tools for event names
- **Consistency:** Both `@Event` and `@Listen` can use the same constant definitions
- **Cross-Component Safety:** Guaranteed matching between event emitters and listeners

## Real-World Example

```typescript
// events.constants.ts
export const COMPONENT_EVENTS = {
  MODAL: {
    OPENED: 'modalOpened',
    CLOSED: 'modalClosed',
    CONFIRMED: 'modalConfirmed'
  },
  FORM: {
    SUBMITTED: 'formSubmitted',
    VALIDATED: 'formValidated',
    RESET: 'formReset'
  }
} as const;

// modal.component.ts
import { COMPONENT_EVENTS } from './events.constants';

@Component({ tag: 'my-modal' })
export class MyModal {
  @Event({ eventName: COMPONENT_EVENTS.MODAL.OPENED }) modalOpened: EventEmitter;
  @Event({ eventName: COMPONENT_EVENTS.MODAL.CLOSED }) modalClosed: EventEmitter;
}

// app.component.ts
import { COMPONENT_EVENTS } from './events.constants';

@Component({ tag: 'my-app' })
export class MyApp {
  @Listen(COMPONENT_EVENTS.MODAL.OPENED)
  handleModalOpened() { ... }
  
  @Listen(COMPONENT_EVENTS.MODAL.CLOSED) 
  handleModalClosed() { ... }
}
```

## Current Workarounds

Developers currently must:
1. Use string literals everywhere (prone to typos)
2. Use constants inconsistently (constants for `@Event`, literals for `@Listen`)
3. Add comments to link constants with string literals:
   ```typescript
   // Emit COMPONENT_EVENTS.MODAL.OPENED
   @Event({ eventName: 'modalOpened' }) modalOpened: EventEmitter;
   
   // Listen to COMPONENT_EVENTS.MODAL.OPENED  
   @Listen('modalOpened') handleModalOpened() { ... }
   ```

This feature would eliminate these workarounds and provide a more robust, maintainable development experience for both event emission and listening.

### Describe the Use Case

Use Case & Motivation
1. Avoid Typos:

```typescript
// Current approach - prone to typos
@Event({ eventName: 'userLoginSuccess' }) loginSuccess: EventEmitter;
@Listen('userLoginSucces') // Typo! Missing 's'
handleLogin() { ... }

// Desired approach - typo-safe
const EVENTS = { USER_LOGIN_SUCCESS: 'userLoginSuccess' } as const;
@Event({ eventName: EVENTS.USER_LOGIN_SUCCESS }) loginSuccess: EventEmitter;
@Listen(EVENTS.USER_LOGIN_SUCCESS) // No typos possible
handleLogin() { ... }
```

2. Maintain DRY Principles:

```typescript
// Single source of truth for event names
export const EVENTS = {
  USER: {
    LOGIN_SUCCESS: 'userLoginSuccess',
    LOGIN_FAILURE: 'userLoginFailure',
    LOGOUT: 'userLogout'
  },
  DATA: {
    LOADED: 'dataLoaded',
    ERROR: 'dataError',
    REFRESH: 'dataRefresh'
  }
} as const;

// Use consistently across components
@Event({ eventName: EVENTS.USER.LOGIN_SUCCESS }) loginSuccess: EventEmitter;
@Listen(EVENTS.USER.LOGIN_SUCCESS) handleLoginSuccess() { ... }

@Event({ eventName: EVENTS.DATA.LOADED }) dataLoaded: EventEmitter;
@Listen(EVENTS.DATA.LOADED) handleDataLoaded() { ... }
```

3. Better Refactoring:
When event names need to change, you only update them in one place instead of searching and replacing string literals throughout the codebase.

4. Cross-Component Consistency:

```typescript
// Component A emits event
@Event({ eventName: EVENTS.USER.LOGIN_SUCCESS }) loginSuccess: EventEmitter;

// Component B listens to the same event
@Listen(EVENTS.USER.LOGIN_SUCCESS) handleUserLogin() { ... }

// Component C also listens
@Listen(EVENTS.USER.LOGIN_SUCCESS) onUserLogin() { ... }
```

### Describe Preferred Solution

Proposed Solution
Allow both decorators to accept constants/variables:

1. `@Listen` decorator:

```typescript
const eventName = 'myEvent';
@Listen(eventName)
@Listen(EVENTS.MY_EVENT)
@Listen(() => EVENTS.MY_EVENT) // factory function alternative
```

2. `@Event` decorator:

```typescript
@Event({ eventName: eventName })
@Event({ eventName: EVENTS.MY_EVENT })
@Event({ eventName: () => EVENTS.MY_EVENT }) // factory function alternative
```

Enhanced Decorator Implementation Example
```typescript
// Enhanced @Listen decorator implementation
function Listen(
  eventName: string | (() => string), 
  opts?: ListenOptions
): MethodDecorator {
  return function(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    // Resolve the event name if it's a function
    const resolvedEventName = typeof eventName === 'function' ? eventName() : eventName;
    
    // Continue with existing Stencil logic using resolvedEventName
    // (This would integrate into Stencil's existing compilation process)
    return applyListenDecorator(target, propertyKey, descriptor, resolvedEventName, opts);
  };
}

// Enhanced @Event decorator implementation  
function Event(opts: EventOptions & { eventName?: string | (() => string) }): PropertyDecorator {
  return function(target: any, propertyKey: string) {
    // Resolve the eventName if it's a function
    const resolvedOpts = { ...opts };
    if (opts.eventName && typeof opts.eventName === 'function') {
      resolvedOpts.eventName = opts.eventName();
    }
    
    // Continue with existing Stencil logic using resolvedOpts
    return applyEventDecorator(target, propertyKey, resolvedOpts);
  };
}

// Usage - no syntax changes needed, just enhanced support
const EVENTS = { 
  MODAL_CLOSED: 'modalClosed',
  USER_LOGIN: 'userLogin' 
} as const;

@Component({ tag: 'my-component' })
export class MyComponent {
  // Now works with functions that return event names
  @Event({ eventName: () => EVENTS.MODAL_CLOSED, bubbles: true })
  modalClosed: EventEmitter;
  
  @Listen(() => EVENTS.USER_LOGIN, { target: 'window' })
  handleUserLogin(event: CustomEvent) { ... }
  
  // Still works with constants/variables
  @Listen(EVENTS.MODAL_CLOSED)
  handleModalClosed() { ... }
  
  @Event({ eventName: EVENTS.USER_LOGIN })
  userLogin: EventEmitter;
  
  // Still works with string literals
  @Listen('click')
  handleClick() { ... }
  
  @Event({ eventName: 'customEvent' })
  customEvent: EventEmitter;
}
```
Type Definitions:

```typescript
// Updated type definitions
interface ListenOptions {
  target?: string;
  capture?: boolean;
  passive?: boolean;
}

interface EventOptions {
  eventName?: string | (() => string);
  composed?: boolean;
  cancelable?: boolean;
  bubbles?: boolean;
}

declare function Listen(
  eventName: string | (() => string), 
  opts?: ListenOptions
): MethodDecorator;

declare function Event(
  opts?: EventOptions
): PropertyDecorator;
```
This approach enhances the existing decorators to detect when a function is passed and resolve it during compilation, while maintaining backward compatibility with all existing usage patterns.

### Describe Alternatives

_No response_

### Related Code

_No response_

### Additional Information

_No response_

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Allow @Listen and @Event decorators to accept constants/variables for event names #6360

Prerequisites

Describe the Feature Request

Feature Request: Allow `@Listen` and `@Event` decorators to accept constants/variables for event names

Problem Description

Current Behavior

Desired Behavior

Use Case & Motivation

Proposed Solution

Enhanced Decorator Implementation Example

Implementation Considerations

Benefits

Real-World Example

Current Workarounds

Describe the Use Case

Describe Preferred Solution

Describe Alternatives

Related Code

Additional Information

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feat: Allow @Listen and @Event decorators to accept constants/variables for event names #6360

Description

Prerequisites

Describe the Feature Request

Feature Request: Allow @Listen and @Event decorators to accept constants/variables for event names

Problem Description

Current Behavior

Desired Behavior

Use Case & Motivation

Proposed Solution

Enhanced Decorator Implementation Example

Implementation Considerations

Benefits

Real-World Example

Current Workarounds

Describe the Use Case

Describe Preferred Solution

Describe Alternatives

Related Code

Additional Information

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Feature Request: Allow `@Listen` and `@Event` decorators to accept constants/variables for event names