test: add css modules. (#17)

Author: knightedcodemonkey

README.md

@@ -82,7 +82,7 @@ Typical customizations:
 - **filter** – Skip certain paths (e.g., storybook-only styles) before compilation.
 - **resolver** – Resolve virtual specifiers the way your bundler does (the repo ships test fixtures for webpack, Vite, and Rspack).
 - **lightningcss** – Pass `true` for defaults or a config object for minification/autoprefixing.
-- **specificityBoost** – Provide a Lightning CSS visitor to bump specificity on selected selectors (e.g., duplicate a class for matching selectors). We compose this with your `lightningcss.visitor`, if provided.
+- **specificityBoost** – Provide a Lightning CSS visitor to bump specificity on selected selectors (e.g., duplicate a class for matching selectors).
 
 ## Examples
 
@@ -150,11 +150,13 @@ module.exports = {
 import { reactJsx } from '@knighted/jsx/react'
 import { createRoot, type Root } from 'react-dom/client'
 import { LitElement, html, unsafeCSS } from 'lit'
-import { Button } from './button.tsx'
-import { knightedCss as reactStyles } from './button.tsx?knighted-css'
+import { customElement } from 'lit/decorators.js'
+import { Showcase } from './showcase.tsx'
+import { knightedCss as showcaseCss } from './showcase.tsx?knighted-css'
 
-export class ButtonWrapper extends LitElement {
-  static styles = [unsafeCSS(reactStyles)]
+@customElement('lit-host')
+export class LitHost extends LitElement {
+  static styles = [unsafeCSS(showcaseCss)]
   #reactRoot?: Root
 
   firstUpdated(): void {
@@ -166,28 +168,36 @@ export class ButtonWrapper extends LitElement {
     super.disconnectedCallback()
   }
 
-  #mountReact() {
-    const outlet = this.renderRoot.querySelector(
-      '[data-react-root]',
-    ) as HTMLDivElement | null
-    if (!outlet) return
-    this.#reactRoot = createRoot(outlet)
-    this.#reactRoot.render(reactJsx`<${Button} />`)
+  #mountReact(): void {
+    if (!this.#reactRoot) {
+      const outlet = this.renderRoot.querySelector(
+        '[data-react-root]',
+      ) as HTMLDivElement | null
+      if (!outlet) return
+      this.#reactRoot = createRoot(outlet)
+    }
+    this.#reactRoot.render(reactJsx`<${Showcase} label="Launch CSS Build" />`)
   }
 
   render() {
     return html`<div data-react-root></div>`
   }
 }
-
-customElements.define('button-wrapper', ButtonWrapper)
 ```
 
 The loader appends `export const knightedCss = "/* compiled css */"` to the module when imported with `?knighted-css`. Keep your main module import separate to preserve its typing; use the query import only for the CSS string.
 
 > [!TIP]
 > The Playwright Rspack demo shows how a Lit host can import specific dialects with `?knighted-css` and pipe them straight into `LitElement.styles`. See [packages/playwright/src/lit-react/lit-host.ts](packages/playwright/src/lit-react/lit-host.ts) for the shadow-root wiring.
 
+#### CSS Modules and stable selectors
+
+CSS Modules hash class names after the loader extracts selectors, so the stylesheet captured by `?knighted-css` never sees those hashed tokens. Provide a second, stable selector (class or data attribute) alongside the module-generated one so both the DOM and the Lit host share a common hook. A minimal example:
+
+```tsx
+<div className={`${styles['css-modules-badge']} css-modules-badge`}>
+```
+
 #### TypeScript support for loader queries
 
 Loader query types ship directly with `@knighted/css`. Reference them once in your project—either by adding `"types": ["@knighted/css/loader-queries"]` to `tsconfig.json` or dropping `/// <reference types="@knighted/css/loader-queries" />` into a global `.d.ts`—and the following ambient modules become available everywhere:

docs/specificity-boost-visitor.md

@@ -31,4 +31,4 @@ const styles = await css('./src/entry.ts', {
 })
 ```
 
-You can plug any Lightning CSS visitor here; we compose it with your `lightningcss.visitor` if provided. Keep the match as narrow as possible to avoid unexpected cascade shifts.
+You can plug any Lightning CSS visitor into `specificityBoost.visitor`; it runs after the built-in `strategy` helpers. Keep the match as narrow as possible to avoid unexpected cascade shifts.

packages/playwright/rspack.config.js

@@ -23,6 +23,9 @@ export default {
       '.js': ['.js', '.ts', '.tsx'],
     },
   },
+  experiments: {
+    css: true,
+  },
   module: {
     rules: [
       {
@@ -49,6 +52,10 @@ export default {
           },
         ],
       },
+      {
+        test: /\.module\.css$/,
+        type: 'css/module',
+      },
       {
         test: /\.[jt]sx?$/,
         resourceQuery: /knighted-css/,
@@ -97,6 +104,7 @@ export default {
       },
       {
         test: /\.css$/,
+        exclude: /\.module\.css$/,
         type: 'asset/source',
       },
       {

packages/playwright/src/global.d.ts

@@ -0,0 +1,4 @@
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export = classes
+}

packages/playwright/src/lit-react/cards/css-modules-card/css-modules-card.module.css

@@ -0,0 +1,33 @@
+.css-modules-badge {
+  display: inline-flex;
+  flex-direction: column;
+  gap: 0.45rem;
+  padding: 1rem 1.25rem;
+  border-radius: 18px;
+  background: linear-gradient(135deg, #312e81, #4c1d95);
+  box-shadow:
+    0 12px 38px rgba(76, 29, 149, 0.45),
+    0 0 0 1px rgba(129, 140, 248, 0.45);
+  border: 1px solid rgba(191, 219, 254, 0.35);
+  color: #e0e7ff;
+}
+
+.css-modules-token {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.35rem 0.75rem;
+  border-radius: 999px;
+  background: rgba(224, 231, 255, 0.15);
+  color: #c7d2fe;
+  font-size: 0.8rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.css-modules-label {
+  font-size: 0.95rem;
+  line-height: 1.4;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+}

packages/playwright/src/lit-react/cards/css-modules-card/css-modules-card.tsx

@@ -0,0 +1,19 @@
+import * as styles from './css-modules-card.module.css'
+
+export const CSS_MODULES_TEST_ID = 'dialect-css-modules'
+
+export function CssModulesCard() {
+  return (
+    <div
+      className={`${styles['css-modules-badge']} css-modules-badge`}
+      data-testid={CSS_MODULES_TEST_ID}
+    >
+      <span className={`${styles['css-modules-token']} css-modules-token`}>
+        css modules
+      </span>
+      <span className={`${styles['css-modules-label']} css-modules-label`}>
+        Stable selectors keep Lit-hosted styles in sync with hashed class names.
+      </span>
+    </div>
+  )
+}

packages/playwright/src/lit-react/showcase.tsx

@@ -4,6 +4,11 @@ import type { JSX } from 'react'
 
 import { BasicCard, BASIC_TEST_ID } from './cards/basic-card/basic-card.js'
 import { LessCard, LESS_TEST_ID } from './cards/less-card/less-card.js'
+import {
+  CssModulesCard,
+  CSS_MODULES_TEST_ID,
+} from './cards/css-modules-card/css-modules-card.js'
+import { knightedCss as cssModulesCss } from './cards/css-modules-card/css-modules-card.js?knighted-css'
 import { SassCard, SASS_TEST_ID } from './cards/sass-card/sass-card.js'
 import { knightedCss as sassCss } from './cards/sass-card/sass-card.js?knighted-css'
 import { ScssCard, SCSS_TEST_ID } from './cards/scss-card/scss-card.js'
@@ -27,6 +32,7 @@ type HostManagedDialect = {
 const cards: DialectCard[] = [
   { id: SCSS_TEST_ID, css: scssCss, Component: ScssCard },
   { id: SASS_TEST_ID, css: sassCss, Component: SassCard },
+  { id: CSS_MODULES_TEST_ID, css: cssModulesCss, Component: CssModulesCard },
   { id: VANILLA_TEST_ID, css: vanillaCss, Component: VanillaCard },
 ]
 

packages/playwright/test/lit-react.spec.ts

@@ -7,6 +7,7 @@ const dialectCases = [
   { id: 'dialect-scss', property: 'color' },
   { id: 'dialect-sass-indented', property: 'color' },
   { id: 'dialect-less', property: 'color' },
+  { id: 'dialect-css-modules', property: 'color' },
   { id: 'dialect-vanilla', property: 'color' },
 ]
 

packages/playwright/test/styles.spec.ts

@@ -5,6 +5,7 @@ const cases = [
   { id: 'dialect-scss', property: 'color' },
   { id: 'dialect-sass-indented', property: 'color' },
   { id: 'dialect-less', property: 'color' },
+  { id: 'dialect-css-modules', property: 'color' },
   { id: 'dialect-vanilla', property: 'color' },
 ]