@knighted/css 1.0.0-alpha.3 → 1.0.0-alpha.4

package/dist/cjs/css.cjs

@@ -10,6 +10,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
 const dependency_tree_1 = __importDefault(require("dependency-tree"));
 const lightningcss_1 = require("lightningcss");
+const helpers_js_1 = require("./helpers.cjs");
 exports.DEFAULT_EXTENSIONS = ['.css', '.scss', '.sass', '.less', '.css.ts'];
 async function css(entry, options = {}) {
     const { css: output } = await cssWithMeta(entry, options);
@@ -41,6 +42,13 @@ async function cssWithMeta(entry, options = {}) {
     let output = chunks.join('\n');
     if (options.lightningcss) {
         const lightningOptions = normalizeLightningOptions(options.lightningcss);
+        const boostVisitor = (0, helpers_js_1.buildSpecificityVisitor)(options.specificityBoost);
+        const combinedVisitor = boostVisitor && lightningOptions.visitor
+            ? (0, lightningcss_1.composeVisitors)([boostVisitor, lightningOptions.visitor])
+            : (boostVisitor ?? lightningOptions.visitor);
+        if (combinedVisitor) {
+            lightningOptions.visitor = combinedVisitor;
+        }
         const { code } = (0, lightningcss_1.transform)({
             ...lightningOptions,
             filename: lightningOptions.filename ?? 'extracted.css',
@@ -48,6 +56,9 @@ async function cssWithMeta(entry, options = {}) {
         });
         output = code.toString();
     }
+    if (options.specificityBoost?.strategy && !options.specificityBoost.visitor) {
+        output = (0, helpers_js_1.applyStringSpecificityBoost)(output, options.specificityBoost);
+    }
     return { css: output, files: files.map(file => file.path) };
 }
 async function resolveEntry(entry, cwd, resolver) {

package/dist/cjs/css.d.cts

@@ -1,5 +1,6 @@
 import type { Options as DependencyTreeOpts } from 'dependency-tree';
 import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
+import { type SpecificitySelector, type SpecificityStrategy } from './helpers.cjs';
 export declare const DEFAULT_EXTENSIONS: string[];
 type LightningCssConfig = boolean | Partial<Omit<LightningTransformOptions<never>, 'code'>>;
 export type CssResolver = (specifier: string, ctx: {
@@ -11,6 +12,11 @@ export interface CssOptions {
     cwd?: string;
     filter?: (filePath: string) => boolean;
     lightningcss?: LightningCssConfig;
+    specificityBoost?: {
+        visitor?: LightningTransformOptions<never>['visitor'];
+        strategy?: SpecificityStrategy;
+        match?: SpecificitySelector[];
+    };
     dependencyTree?: Partial<Omit<DependencyTreeOpts, 'filename' | 'directory'>>;
     resolver?: CssResolver;
     peerResolver?: PeerLoader;

package/dist/cjs/helpers.cjs

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSpecificityVisitor = buildSpecificityVisitor;
+exports.serializeSelector = serializeSelector;
+exports.escapeRegex = escapeRegex;
+exports.findLastClassName = findLastClassName;
+exports.applyStringSpecificityBoost = applyStringSpecificityBoost;
+function buildSpecificityVisitor(boost) {
+    if (!boost)
+        return undefined;
+    if (boost.visitor)
+        return boost.visitor;
+    if (!boost.strategy)
+        return undefined;
+    const matchers = (boost.match ?? []).map(m => typeof m === 'string' ? new RegExp(`^${escapeRegex(m)}$`) : m);
+    const shouldApply = (selectorStr) => matchers.length === 0 ? true : matchers.some(rx => rx.test(selectorStr));
+    if (boost.strategy.type === 'repeat-class') {
+        const times = Math.max(1, boost.strategy.times ?? 1);
+        const visitor = {
+            Rule: {
+                style(rule) {
+                    if (!rule || !Array.isArray(rule.selectors))
+                        return rule;
+                    const newSelectors = rule.selectors.map((sel) => {
+                        const selectorStr = serializeSelector(sel);
+                        if (!shouldApply(selectorStr))
+                            return sel;
+                        const lastClassName = findLastClassName(selectorStr);
+                        if (!lastClassName)
+                            return sel;
+                        const repeats = Array.from({ length: times }, () => ({
+                            type: 'class',
+                            value: lastClassName,
+                        }));
+                        return [...sel, ...repeats];
+                    });
+                    return { ...rule, selectors: newSelectors };
+                },
+            },
+        };
+        return visitor;
+    }
+    if (boost.strategy.type === 'append-where') {
+        const token = boost.strategy.token;
+        const visitor = {
+            Rule: {
+                style(rule) {
+                    if (!rule || !Array.isArray(rule.selectors))
+                        return rule;
+                    const newSelectors = rule.selectors.map((sel) => {
+                        const selectorStr = serializeSelector(sel);
+                        if (!shouldApply(selectorStr))
+                            return sel;
+                        return [
+                            ...sel,
+                            {
+                                type: 'pseudo-class',
+                                kind: 'where',
+                                selectors: [[{ type: 'class', value: token.replace(/^\./, '') }]],
+                            },
+                        ];
+                    });
+                    return { ...rule, selectors: newSelectors };
+                },
+            },
+        };
+        return visitor;
+    }
+    return undefined;
+}
+function serializeSelector(sel) {
+    return sel
+        .map(node => {
+        if (node.type === 'class')
+            return `.${node.value ?? node.name ?? ''}`;
+        if (node.type === 'id')
+            return `#${node.value ?? node.name ?? ''}`;
+        if (node.type === 'type')
+            return node.name ?? '';
+        if (node.type === 'pseudo-class')
+            return `:${node.kind ?? ''}`;
+        if (node.type === 'combinator')
+            return ` ${node.value ?? ''} `;
+        return '';
+    })
+        .join('')
+        .trim();
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function findLastClassName(selector) {
+    let match;
+    let last;
+    const rx = /\.([A-Za-z0-9_-]+)/g;
+    while ((match = rx.exec(selector)) !== null) {
+        last = match[1];
+    }
+    return last;
+}
+function applyStringSpecificityBoost(css, boost) {
+    if (!boost.strategy)
+        return css;
+    const matchers = (boost.match ?? []).map(m => typeof m === 'string' ? new RegExp(`\\.${escapeRegex(m)}(?![\\w-])`, 'g') : m);
+    const applyAll = matchers.length === 0;
+    if (boost.strategy.type === 'repeat-class') {
+        const times = Math.max(1, boost.strategy.times ?? 1);
+        const duplicate = (cls) => cls + cls.repeat(times);
+        if (applyAll) {
+            return css.replace(/\.[A-Za-z0-9_-]+/g, m => duplicate(m));
+        }
+        let result = css;
+        for (const rx of matchers) {
+            result = result.replace(rx, m => duplicate(m));
+        }
+        return result;
+    }
+    if (boost.strategy.type === 'append-where') {
+        const token = boost.strategy.token.replace(/^\./, '');
+        const suffix = `:where(.${token})`;
+        if (applyAll) {
+            return css.replace(/\.[A-Za-z0-9_-]+/g, m => `${m}${suffix}`);
+        }
+        let result = css;
+        for (const rx of matchers) {
+            result = result.replace(rx, m => `${m}${suffix}`);
+        }
+        return result;
+    }
+    return css;
+}

package/dist/cjs/helpers.d.cts

@@ -0,0 +1,27 @@
+import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
+export type SpecificitySelector = string | RegExp;
+export type LightningVisitor = LightningTransformOptions<Record<string, never>>['visitor'];
+export type SpecificityStrategy = {
+    type: 'append-where';
+    token: string;
+} | {
+    type: 'repeat-class';
+    times?: number;
+};
+export declare function buildSpecificityVisitor(boost?: {
+    visitor?: LightningVisitor;
+    strategy?: SpecificityStrategy;
+    match?: SpecificitySelector[];
+}): LightningVisitor | undefined;
+export declare function serializeSelector(sel: Array<{
+    type: string;
+    value?: string;
+    name?: string;
+    kind?: string;
+}>): string;
+export declare function escapeRegex(str: string): string;
+export declare function findLastClassName(selector: string): string | undefined;
+export declare function applyStringSpecificityBoost(css: string, boost: {
+    strategy?: SpecificityStrategy;
+    match?: SpecificitySelector[];
+}): string;

package/dist/css.d.ts

@@ -1,5 +1,6 @@
 import type { Options as DependencyTreeOpts } from 'dependency-tree';
 import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
+import { type SpecificitySelector, type SpecificityStrategy } from './helpers.js';
 export declare const DEFAULT_EXTENSIONS: string[];
 type LightningCssConfig = boolean | Partial<Omit<LightningTransformOptions<never>, 'code'>>;
 export type CssResolver = (specifier: string, ctx: {
@@ -11,6 +12,11 @@ export interface CssOptions {
     cwd?: string;
     filter?: (filePath: string) => boolean;
     lightningcss?: LightningCssConfig;
+    specificityBoost?: {
+        visitor?: LightningTransformOptions<never>['visitor'];
+        strategy?: SpecificityStrategy;
+        match?: SpecificitySelector[];
+    };
     dependencyTree?: Partial<Omit<DependencyTreeOpts, 'filename' | 'directory'>>;
     resolver?: CssResolver;
     peerResolver?: PeerLoader;

package/dist/css.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import dependencyTree from 'dependency-tree';
-import { transform as lightningTransform, } from 'lightningcss';
+import { composeVisitors, transform as lightningTransform, } from 'lightningcss';
+import { applyStringSpecificityBoost, buildSpecificityVisitor, } from './helpers.js';
 export const DEFAULT_EXTENSIONS = ['.css', '.scss', '.sass', '.less', '.css.ts'];
 export async function css(entry, options = {}) {
     const { css: output } = await cssWithMeta(entry, options);
@@ -33,6 +34,13 @@ export async function cssWithMeta(entry, options = {}) {
     let output = chunks.join('\n');
     if (options.lightningcss) {
         const lightningOptions = normalizeLightningOptions(options.lightningcss);
+        const boostVisitor = buildSpecificityVisitor(options.specificityBoost);
+        const combinedVisitor = boostVisitor && lightningOptions.visitor
+            ? composeVisitors([boostVisitor, lightningOptions.visitor])
+            : (boostVisitor ?? lightningOptions.visitor);
+        if (combinedVisitor) {
+            lightningOptions.visitor = combinedVisitor;
+        }
         const { code } = lightningTransform({
             ...lightningOptions,
             filename: lightningOptions.filename ?? 'extracted.css',
@@ -40,6 +48,9 @@ export async function cssWithMeta(entry, options = {}) {
         });
         output = code.toString();
     }
+    if (options.specificityBoost?.strategy && !options.specificityBoost.visitor) {
+        output = applyStringSpecificityBoost(output, options.specificityBoost);
+    }
     return { css: output, files: files.map(file => file.path) };
 }
 async function resolveEntry(entry, cwd, resolver) {

package/dist/helpers.d.ts

@@ -0,0 +1,27 @@
+import { type TransformOptions as LightningTransformOptions } from 'lightningcss';
+export type SpecificitySelector = string | RegExp;
+export type LightningVisitor = LightningTransformOptions<Record<string, never>>['visitor'];
+export type SpecificityStrategy = {
+    type: 'append-where';
+    token: string;
+} | {
+    type: 'repeat-class';
+    times?: number;
+};
+export declare function buildSpecificityVisitor(boost?: {
+    visitor?: LightningVisitor;
+    strategy?: SpecificityStrategy;
+    match?: SpecificitySelector[];
+}): LightningVisitor | undefined;
+export declare function serializeSelector(sel: Array<{
+    type: string;
+    value?: string;
+    name?: string;
+    kind?: string;
+}>): string;
+export declare function escapeRegex(str: string): string;
+export declare function findLastClassName(selector: string): string | undefined;
+export declare function applyStringSpecificityBoost(css: string, boost: {
+    strategy?: SpecificityStrategy;
+    match?: SpecificitySelector[];
+}): string;

package/dist/helpers.js

@@ -0,0 +1,124 @@
+export function buildSpecificityVisitor(boost) {
+    if (!boost)
+        return undefined;
+    if (boost.visitor)
+        return boost.visitor;
+    if (!boost.strategy)
+        return undefined;
+    const matchers = (boost.match ?? []).map(m => typeof m === 'string' ? new RegExp(`^${escapeRegex(m)}$`) : m);
+    const shouldApply = (selectorStr) => matchers.length === 0 ? true : matchers.some(rx => rx.test(selectorStr));
+    if (boost.strategy.type === 'repeat-class') {
+        const times = Math.max(1, boost.strategy.times ?? 1);
+        const visitor = {
+            Rule: {
+                style(rule) {
+                    if (!rule || !Array.isArray(rule.selectors))
+                        return rule;
+                    const newSelectors = rule.selectors.map((sel) => {
+                        const selectorStr = serializeSelector(sel);
+                        if (!shouldApply(selectorStr))
+                            return sel;
+                        const lastClassName = findLastClassName(selectorStr);
+                        if (!lastClassName)
+                            return sel;
+                        const repeats = Array.from({ length: times }, () => ({
+                            type: 'class',
+                            value: lastClassName,
+                        }));
+                        return [...sel, ...repeats];
+                    });
+                    return { ...rule, selectors: newSelectors };
+                },
+            },
+        };
+        return visitor;
+    }
+    if (boost.strategy.type === 'append-where') {
+        const token = boost.strategy.token;
+        const visitor = {
+            Rule: {
+                style(rule) {
+                    if (!rule || !Array.isArray(rule.selectors))
+                        return rule;
+                    const newSelectors = rule.selectors.map((sel) => {
+                        const selectorStr = serializeSelector(sel);
+                        if (!shouldApply(selectorStr))
+                            return sel;
+                        return [
+                            ...sel,
+                            {
+                                type: 'pseudo-class',
+                                kind: 'where',
+                                selectors: [[{ type: 'class', value: token.replace(/^\./, '') }]],
+                            },
+                        ];
+                    });
+                    return { ...rule, selectors: newSelectors };
+                },
+            },
+        };
+        return visitor;
+    }
+    return undefined;
+}
+export function serializeSelector(sel) {
+    return sel
+        .map(node => {
+        if (node.type === 'class')
+            return `.${node.value ?? node.name ?? ''}`;
+        if (node.type === 'id')
+            return `#${node.value ?? node.name ?? ''}`;
+        if (node.type === 'type')
+            return node.name ?? '';
+        if (node.type === 'pseudo-class')
+            return `:${node.kind ?? ''}`;
+        if (node.type === 'combinator')
+            return ` ${node.value ?? ''} `;
+        return '';
+    })
+        .join('')
+        .trim();
+}
+export function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function findLastClassName(selector) {
+    let match;
+    let last;
+    const rx = /\.([A-Za-z0-9_-]+)/g;
+    while ((match = rx.exec(selector)) !== null) {
+        last = match[1];
+    }
+    return last;
+}
+export function applyStringSpecificityBoost(css, boost) {
+    if (!boost.strategy)
+        return css;
+    const matchers = (boost.match ?? []).map(m => typeof m === 'string' ? new RegExp(`\\.${escapeRegex(m)}(?![\\w-])`, 'g') : m);
+    const applyAll = matchers.length === 0;
+    if (boost.strategy.type === 'repeat-class') {
+        const times = Math.max(1, boost.strategy.times ?? 1);
+        const duplicate = (cls) => cls + cls.repeat(times);
+        if (applyAll) {
+            return css.replace(/\.[A-Za-z0-9_-]+/g, m => duplicate(m));
+        }
+        let result = css;
+        for (const rx of matchers) {
+            result = result.replace(rx, m => duplicate(m));
+        }
+        return result;
+    }
+    if (boost.strategy.type === 'append-where') {
+        const token = boost.strategy.token.replace(/^\./, '');
+        const suffix = `:where(.${token})`;
+        if (applyAll) {
+            return css.replace(/\.[A-Za-z0-9_-]+/g, m => `${m}${suffix}`);
+        }
+        let result = css;
+        for (const rx of matchers) {
+            result = result.replace(rx, m => `${m}${suffix}`);
+        }
+        return result;
+    }
+    return css;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.4",
   "description": "A build-time utility that traverses JavaScript/TypeScript module dependency graphs to extract, compile, and optimize all imported CSS into a single, in-memory string.",
   "type": "module",
   "main": "./dist/css.js",