feat(useOverlay): add on method to listen emits from component

[edimitchel]

🔗 Linked issue

Resolved #5233

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Introducing this new on method permits to easy bind emits event before opening for let developer to only think about props in create/open/patch methods.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[pkg-pr-new]

npm i https://pkg.pr.new/@nuxt/ui@5244

commit: f7a2b45

[edimitchel]

I forget the API instance documentation + Caveats section miss a warning about the limitation of the composable.

We need to discuss about its limitation is caused by typescript limitations

[vercel]

Suggested change

	overlay.emits[event as string] = callback
	// For close events, preserve the default close behavior by chaining callbacks
	if (event === 'close') {
	const existingHandler = overlay.emits[event as string]
	if (existingHandler) {
	overlay.emits[event as string] = (...args: Parameters<typeof callback>) => {
	callback(...args)
	existingHandler(...args)
	}
	} else {
	overlay.emits[event as string] = callback
	}
	} else {
	overlay.emits[event as string] = callback
	}

The on() method replaces the default close event handler instead of preserving it, which breaks automatic overlay closure when registering close event listeners.

View Details

Analysis

useOverlay.on() replaces default close handler breaking automatic overlay closure

What fails: useOverlay.on('close', callback) in src/runtime/composables/useOverlay.ts:214 replaces the default close handler instead of chaining it, preventing automatic overlay closure when user callbacks don't explicitly call modal.close()

How to reproduce:

const { create } = useOverlay()
const modal = create(Component)
modal.open()

// Register close handler that doesn't call modal.close()
modal.on('close', (value) => {
  console.log('Close event received:', value)
  // No modal.close() call here
})

// When component emits close event, overlay stays open
component.$emit('close', 'result') // Overlay remains open

Result: Overlay stays open because default (value) => close(id, value) handler is replaced by user callback

Expected: Overlay should close automatically even when user callback doesn't call modal.close(), preserving the default close behavior established in create() at line 118

Root cause: Line 214 uses direct assignment overlay.emits[event as string] = callback instead of chaining handlers for close events