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

.changeset/config.json

@@ -24,6 +24,7 @@
     "preact-ts",
     "svelte-ts",
     "vanilla-ts",
+    "lit-ts",
     "website"
   ]
 }

e2e/_utils.ts

@@ -1,15 +1,65 @@
 import AxeBuilder from "@axe-core/playwright"
 import { expect, type Locator, type Page } from "@playwright/test"
 
-export async function a11y(page: Page, selector = "[data-part=root]") {
+// Types and Framework Context Detection
+export type DomMode = "shadow-dom" | "light-dom"
+
+// The context is determined by environment variables at test runtime
+// VITE_DOM_MODE is the primary control (matches client-side behavior)
+// Examples:
+// - `VITE_DOM_MODE=shadow-dom FRAMEWORK=react npx playwright test` (force Shadow DOM in React)
+// - `VITE_DOM_MODE=light-dom FRAMEWORK=lit npx playwright test` (force Light DOM in Lit)
+// - `FRAMEWORK=lit npx playwright test` (default Lit behavior: Shadow DOM)
+export const DOM_MODE: DomMode =
+  process.env.VITE_DOM_MODE === "light-dom" ? "light-dom" : process.env.FRAMEWORK === "lit" ? "shadow-dom" : "light-dom"
+
+console.log(`Running E2E tests in '${DOM_MODE}' context for '${process.env.FRAMEWORK}'.`)
+
+/**
+ * Context-aware utility to locate a component part defined by a 'part' or 'data-part' attribute.
+ * This function abstracts the structural differences between Shadow DOM and Light DOM implementations.
+ *
+ * @param parent The root Playwright Page or a parent Locator to search within
+ * @param hostSelector A unique selector for the component's host/root element (e.g., 'accordion-page', '[data-testid="accordion-root"]')
+ * @param partName The name of the part to locate (e.g., 'trigger', 'content')
+ * @returns A Playwright Locator for the requested part
+ */
+export function getPart(parent: Page | Locator, hostSelector: string, partName: string): Locator {
+  // Use [part="..."] for CSS Shadow Parts standard, fallback to [data-part="..."]
+  const partSelector = `[part="${partName}"], [data-part="${partName}"]`
+
+  if (DOM_MODE === "shadow-dom") {
+    // For Shadow DOM, use a descendant combinator. Playwright's engine will
+    // pierce the shadow root of the element matching hostSelector.
+    return parent.locator(`${hostSelector} ${partSelector}`)
+  } else {
+    // For Light DOM, the structure might be a direct child or a deeper descendant.
+    // In many simple cases, the selector is identical to the shadow DOM version.
+    return parent.locator(`${hostSelector} ${partSelector}`)
+  }
+}
+
+/**
+ * Performs an accessibility scan, optionally scoped to a specific selector.
+ * @param page The Playwright Page object
+ * @param selector Optional selector to scope the scan (defaults to "[data-part=root]")
+ * @param hostSelector A CSS selector for a shadow host element
+ */
+export async function a11y(page: Page, selector = "[data-part=root]", hostSelector?: string) {
   await page.waitForSelector(selector)
 
-  const results = await new AxeBuilder({ page: page as any })
-    .disableRules(["color-contrast"])
-    .include(selector)
-    .analyze()
+  let selection = new AxeBuilder({ page: page as any }).disableRules(["color-contrast"])
+
+  if (hostSelector && DOM_MODE === "shadow-dom") {
+    selection = selection.include(hostSelector)
+  }
+  if (selector) {
+    selection = selection.include(selector)
+  }
+
+  const accessibilityScanResults = await selection.analyze()
 
-  expect(results.violations).toEqual([])
+  expect(accessibilityScanResults.violations).toEqual([])
 }
 
 export const testid = (part: string) => `[data-testid=${esc(part)}]`

e2e/checkbox.e2e.ts

@@ -1,64 +1,66 @@
-import { expect, type Page, test } from "@playwright/test"
-import { a11y, controls, part, testid } from "./_utils"
+import { expect, test } from "@playwright/test"
+import { CheckboxModel } from "./models/checkbox.model"
 
-const root = part("root")
-const label = part("label")
-const control = part("control")
-const input = testid("hidden-input")
-
-const expectToBeChecked = async (page: Page) => {
-  await expect(page.locator(root)).toHaveAttribute("data-state", "checked")
-  await expect(page.locator(label)).toHaveAttribute("data-state", "checked")
-  await expect(page.locator(control)).toHaveAttribute("data-state", "checked")
-}
+let I: CheckboxModel
 
 test.beforeEach(async ({ page }) => {
-  await page.goto("/checkbox")
+  I = new CheckboxModel(page)
+  await I.goto()
 })
 
-test("should have no accessibility violation", async ({ page }) => {
-  await a11y(page)
+test("should have no accessibility violation", async () => {
+  await I.checkAccessibility()
 })
 
-test("should be checked when clicked", async ({ page }) => {
-  await page.click(root)
-  await expectToBeChecked(page)
+test("should be checked when clicked", async () => {
+  await I.root.click()
+  await I.expectToBeChecked()
 })
 
 test("should be focused when page is tabbed", async ({ page }) => {
   await page.click("main")
   await page.keyboard.press("Tab")
-  await expect(page.locator(input)).toBeFocused()
-  await expect(page.locator(control)).toHaveAttribute("data-focus", "")
+  await expect(I.input).toBeFocused()
+  await expect(I.control).toHaveAttribute("data-focus", "")
 })
 
 test("should be checked when spacebar is pressed while focused", async ({ page }) => {
   await page.click("main")
   await page.keyboard.press("Tab")
   await page.keyboard.press(" ")
-  await expectToBeChecked(page)
+  await I.expectToBeChecked()
 })
 
-test("should have disabled attributes when disabled", async ({ page }) => {
-  await controls(page).bool("disabled")
-  await expect(page.locator(input)).toBeDisabled()
+test("should have disabled attributes when disabled", async () => {
+  await I.controls.bool("disabled")
+  await I.expectToBeDisabled()
 })
 
 test("should not be focusable when disabled", async ({ page }) => {
-  await controls(page).bool("disabled")
+  await I.controls.bool("disabled")
   await page.click("main")
   await page.keyboard.press("Tab")
-  await expect(page.locator(input)).not.toBeFocused()
+  await expect(I.input).not.toBeFocused()
 })
 
 test("input is not blurred on label click", async ({ page }) => {
   let blurCount = 0
   await page.exposeFunction("trackBlur", () => blurCount++)
-  await page.locator(input).evaluate((input) => {
+  await I.input.evaluate((input) => {
     input.addEventListener("blur", (window as any).trackBlur)
   })
-  await page.click(label)
-  await page.click(label)
-  await page.click(label)
+  await I.label.click()
+  await I.label.click()
+  await I.label.click()
   expect(blurCount).toBe(0)
 })
+
+test("reset form should restore initial state", async () => {
+  await expect(I.input).not.toBeChecked()
+
+  await I.label.click()
+  await expect(I.input).toBeChecked()
+
+  await I.resetButton.click()
+  await expect(I.input).not.toBeChecked()
+})

e2e/collapsible.e2e.ts

@@ -1,30 +1,34 @@
 import { expect, test } from "@playwright/test"
-import { a11y, part } from "./_utils"
+import { CollapsibleModel } from "./models/collapsible.model"
 
-const trigger = part("trigger")
-const content = part("content")
+let I: CollapsibleModel
 
 test.describe("collapsible", () => {
   test.beforeEach(async ({ page }) => {
-    await page.goto("/collapsible")
+    I = new CollapsibleModel(page)
+    await I.goto()
   })
 
-  test("should have no accessibility violation", async ({ page }) => {
-    await a11y(page)
+  test("should have no accessibility violation", async () => {
+    await I.checkAccessibility()
   })
 
-  test("[toggle] should be open when clicked", async ({ page }) => {
-    await page.click(trigger)
-    await expect(page.locator(content)).toBeVisible()
+  test("[toggle] should be open when clicked", async () => {
+    await I.clickTrigger()
+    await I.seeContent()
 
-    await page.click(trigger)
-    await expect(page.locator(content)).not.toBeVisible()
+    await I.clickTrigger()
+    await I.dontSeeContent()
   })
 
-  test.skip("[closed] content should not be reachable via tab key", async ({ page }) => {
-    await page.click(trigger)
-    await page.click(trigger)
-    await page.keyboard.press("Tab")
-    await expect(page.getByRole("button", { name: "Open" })).toBeFocused()
+  test("[closed] content should not be reachable via tab key", async () => {
+    await I.clickTrigger()
+    await I.seeContent()
+
+    await I.clickTrigger()
+    await I.dontSeeContent()
+
+    await I.pressKey("Tab")
+    await expect(I.host.getByTestId("open-button")).toBeFocused()
   })
 })