feat: create @zag-js/lit (WIP)

[nikparo]

Closes #

📝 Description

Add a brief description

WIP work on creating a @zag-js/lit framework. Adds packages/frameworks/lit and examples/lit-ts, and adapts e2e/ testing suite to optionally work with shadow-dom.

This PR is only open for visibility and comments, it's not ready to be merged.

NOTE: Video is from my dev/lit branch that combines several other branches, including:
#2694
#2697
#2695

⛳️ Current behavior (updates)

Please describe the current behavior that you are modifying

🚀 New behavior

Please describe the behavior or changes this PR adds

Screen.Recording.2025-09-09.at.12.46.26.mov

💣 Is this a breaking change (Yes/No):

📝 Additional Information

Related discussion threads:
#2681
#1210

Thank you @gperdomor for your work on #2608

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5b51fc9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
zag-nextjs	Ready	Preview	Sep 9, 2025 9:57am
zag-solid	Ready	Preview	Sep 9, 2025 9:57am
zag-svelte	Ready	Preview	Sep 9, 2025 9:57am
zag-vue	Ready	Preview	Sep 9, 2025 9:57am
zag-website	Ready	Preview	Sep 9, 2025 9:57am

[gperdomor]

Amazing job @nikparo… I hope that this can be merged soon ❤️

[irontitan76]

This is awesome! Thank you, @nikparo, for putting this together. What is needed to push this across the line—reviews, more direct contributions, or something else altogether?

[gperdomor]

any progress with this?

[nikparo]

@gperdomor @irontitan76 Thanks for the interest. This did fall on the backburner for a while due to more pressing matters taking priority, though I've been working on it a bit here and there.

The main thing I've been working on is to verify that shadow-dom was working properly by refactoring the examples / e2e tests so that the shadow-dom boundaries are more realistically placed. It has been a bit challenging tbh - shadow-dom blocks things like document.getElementById, e2e targeting needs to work differently for shadow-dom and light-dom, but still work with all the frameworks, etc.

I'm still fairly optimistic that shadow-dom support is doable though - I've recently gotten the menu-nested example working pretty well using 3 separate menu-elements using both slots and cross-boundary querying, which is a pretty good proof-of-concept imo. It's been quite experimental, but will try and update my branches here once I've cleaned it up a bit.

One open question though is whether we should even try to support shadow-dom for the initial PR. It would certainly be much quicker to get the initial framework ready to be merged if we forgo that. Lit examples + e2e tests could then be updated on a component by component basis to use shadow-dom until all do.

Side note: Lit supports light-dom use, but doesn't recommend it, as slots and dom/style scoping isn't available.

[gperdomor]

@nikparo I'm not an expert and I don't know how can I help you but I think that having an initial framework in place, even without the shadow-dom support, would be great... Then all the missing things can be improved with other small MRs...

[segunadebayo]

Hey @nikparo, heads up — I'm closing #2695 since the mergeProps event handler prefix issue is a Lit-specific concern that should be handled here in the Lit adapter, not in the menu connect logic.

For all currently supported frameworks, normalizeProps preserves the on prefix, so core mergeProps chains handlers correctly. The issue only surfaces when a normalizer changes the prefix (e.g., onClick → @click in Lit).

I'd suggest providing a custom mergeProps in @zag-js/lit that bridges the @ ↔ on prefix gap:

// packages/frameworks/lit/src/merge-props.ts
import { mergeProps as coreMergeProps } from "@zag-js/core"

export function mergeProps<T extends Record<string, any>>(
  ...args: Array<T | undefined>
): T {
  // Convert @-prefixed event handlers to on- prefix
  // so core mergeProps chains them correctly, then convert back.
  const normalized = args.map((props) => {
    if (!props) return props
    const result: Record<string, any> = {}
    for (const key in props) {
      if (key.startsWith("@")) {
        result[`on${key.slice(1)}`] = props[key]
      } else {
        result[key] = props[key]
      }
    }
    return result as T
  })

  const merged = coreMergeProps(...normalized)

  // Convert back to @-prefixed
  const result: Record<string, any> = {}
  for (const key in merged) {
    if (key.startsWith("on") && typeof merged[key] === "function") {
      result[`@${key.slice(2).toLowerCase()}`] = merged[key]
    } else {
      result[key] = merged[key]
    }
  }

  return result as T
}

This keeps the framework-specific concern in the adapter layer. Every other framework re-exports mergeProps from core — Lit would just provide its own.