Auto-generate stable class variants from source styles

[morganney]

Auto-generate stable class variants from source styles

Problem

Currently, users must manually opt into stable selectors:

Sass:

.icon {
  @include knighted.stable('icon') { /* ... */ }
}

Less:

.icon {
  .stable(icon, { /* ... */ });
}

For large stylesheets or migrations, this can be tedious and error-prone.

---

Proposal

Add an optional mode where @knighted/css (loader or PostCSS plugin) can automatically emit stable variants for all selectors in a given file.

Use cases:

• Large stylesheets where manually wrapping every class is tedious.
• Migrating existing styles to support shadow DOM without refactoring every rule.
• Design systems that want stable classes for all components by default.

---

Possible API

Via loader option:

{
  loader: '@knighted/css/loader',
  options: {
    autoStable: true, // or { namespace: 'myapp', include: /^\.icon/ }
  }
}

Via file-level pragma:

/* @knighted-auto-stable */

.icon { /* ... */ }
.button { /* ... */ }

Loader would transform this to:

.icon,
.knighted-icon { /* ... */ }

.button,
.knighted-button { /* ... */ }

---

Implementation notes

• Could be a PostCSS plugin (postcss-knighted-stable) that runs after Sass/Less compilation.
• Would need heuristics to:
  • Only duplicate class selectors (not IDs, attributes, pseudo-classes in isolation).
  • Optionally support a filter (e.g., only classes matching a pattern).
• Should play nicely with existing manual @include knighted.stable() (don't double-emit).
• Needs to handle nested selectors gracefully (e.g., .parent .child).

---

Open questions

• Should this be opt-in per file, per directory, or globally?
• How to handle nested selectors (e.g., .parent .child)?
  • Generate .knighted-parent .child?
  • Generate .knighted-parent .knighted-child?
  • Only top-level classes?
• Should it support other selector types (IDs, attributes)?
• How to avoid conflicts with existing manual stable class usage?

---

Benefits

• Reduces manual work for large codebases.
• Makes adoption easier for teams migrating to shadow DOM.
• Provides a clear path from "no stable classes" to "all stable" without big refactors.

[morganney]

Proposed Solution: Lightning CSS Visitor Approach

I think the best approach for auto-generating stable selectors would be to leverage the Lightning CSS visitor pattern that's already integrated in css.ts.

Why Lightning CSS is Ideal

The loader already runs before CSS Modules hashing, which means:

1. ✅ We have access to original, unhashed class names (.button not .button_abc123)
2. ✅ Lightning CSS is already configured and running in the extraction pipeline
3. ✅ AST-based transformation handles all the edge cases mentioned in the issue

Proposed Implementation

1. Add a new autoStable option to KnightedCssLoaderOptions:

export interface KnightedCssLoaderOptions extends CssOptions {
  vanilla?: KnightedCssVanillaOptions
  stableNamespace?: string
  autoStable?: boolean | {
    include?: RegExp  // Filter which classes to transform
    strategy?: 'top-level' | 'all-classes'  // Handle nested selectors
  }
}

2. Create a new Lightning CSS visitor in css.ts:

function buildAutoStableVisitor(options: AutoStableOptions) {
  return {
    Rule(rule) {
      visit(rule.value.selectors, (selector) => {
        if (!isClassSelector(selector)) return selector
        if (options.include && !options.include.test(selector)) return selector
        
        // Check if already has stable variant
        const hasStable = rule.value.selectors.some(s => 
          s.includes(options.namespace)
        )
        if (hasStable) return selector  // Skip, avoid duplicates
        
        const stableVariant = createStableSelector(selector, options)
        return [selector, stableVariant]  // Emit both variants
      })
    }
  }
}

3. Integrate into the existing visitor composition (around line 106 in css.ts):

if (options.lightningcss) {
  const lightningOptions = normalizeLightningOptions(options.lightningcss)
  
  const autoStableVisitor = options.autoStable 
    ?  buildAutoStableVisitor({
        namespace: options.stableNamespace ?? 'knighted',
        filter: typeof options.autoStable === 'object' ? options.autoStable.include : undefined,
        strategy: typeof options. autoStable === 'object' ? options.autoStable.strategy : 'top-level'
      })
    : undefined
  
  const boostVisitor = buildSpecificityVisitor(options.specificityBoost)
  
  const combinedVisitor = composeVisitors([
    autoStableVisitor,
    boostVisitor,
    lightningOptions.visitor
  ].filter(Boolean))
  
  // ... rest of transform
}

Usage Examples

Webpack config:

{
  loader: '@knighted/css/loader',
  options: {
    autoStable: true,  // Enable for all classes
    stableNamespace: 'myapp',
    lightningcss: true
  }
}

With filtering:

{
  loader: '@knighted/css/loader',
  options: {
    autoStable: {
      include: /^\.icon/,  // Only classes starting with .icon
      strategy: 'top-level'  // Only transform top-level classes in nested selectors
    },
    lightningcss: true
  }
}

Addressing Open Questions

1. Should this be opt-in per file, per directory, or globally?

• Globally via loader config (as shown above)
• Per-file via pragma detection: detect /* @knighted-auto-stable */ in CSS and conditionally enable the visitor

2. How to handle nested selectors?

• strategy: 'top-level': .parent .child → .knighted-parent .child
• strategy: 'all-classes': .parent .child → .knighted-parent .knighted-child

3. Should it support other selector types?

• Start with class selectors only (most common use case)
• Could extend later based on feedback

4. How to avoid conflicts with manual stable classes?

• Visitor checks if selector already contains the namespace prefix and skips transformation

Benefits of This Approach

✅ Works with existing architecture: Integrates cleanly with the current Lightning CSS pipeline
✅ Handles all edge cases: AST-based parsing correctly handles nested selectors, pseudo-classes, etc.
✅ No duplicate processing: Single transformation pass during CSS extraction
✅ Type-safe: Generated stable classes still work with generateTypes.ts since it also calls cssWithMeta()
✅ Framework-agnostic: Works with Sass, Less, CSS, and Vanilla Extract
✅ Performant: Lightning CSS visitors are optimized and already running

Next Steps

1. Add the autoStable option to KnightedCssLoaderOptions
2. Implement buildAutoStableVisitor()
3. Integrate it into the visitor composition in css.ts
4. Add tests for various selector patterns and edge cases
5. Update documentation with usage examples

[knightedcodemonkey]

That won't work because it will get the hashed selectors applied to the HTML out of sync with the ones used in the CSS.