@knighted/css 1.0.0-rc.6 → 1.0.0-rc.8

package/dist/cjs/loader.cjs

@@ -4,11 +4,25 @@ exports.pitch = void 0;
 const css_js_1 = require("./css.cjs");
 const moduleInfo_js_1 = require("./moduleInfo.cjs");
 const loaderInternals_js_1 = require("./loaderInternals.cjs");
+const stableSelectorsLiteral_js_1 = require("./stableSelectorsLiteral.cjs");
+const stableNamespace_js_1 = require("./stableNamespace.cjs");
 const DEFAULT_EXPORT_NAME = 'knightedCss';
 const loader = async function loader(source) {
-    const { cssOptions, vanillaOptions } = resolveLoaderOptions(this);
+    const { cssOptions, vanillaOptions, stableNamespace: optionNamespace, } = resolveLoaderOptions(this);
+    const resolvedNamespace = (0, stableNamespace_js_1.resolveStableNamespace)(optionNamespace);
+    const typesRequested = (0, loaderInternals_js_1.hasQueryFlag)(this.resourceQuery, loaderInternals_js_1.TYPES_QUERY_FLAG);
     const css = await extractCss(this, cssOptions);
-    const injection = buildInjection(css);
+    const stableSelectorsLiteral = typesRequested
+        ? (0, stableSelectorsLiteral_js_1.buildStableSelectorsLiteral)({
+            css,
+            namespace: resolvedNamespace,
+            resourcePath: this.resourcePath,
+            emitWarning: message => emitKnightedWarning(this, message),
+        })
+        : undefined;
+    const injection = buildInjection(css, {
+        stableSelectorsLiteral: stableSelectorsLiteral?.literal,
+    });
     const isStyleModule = this.resourcePath.endsWith('.css.ts');
     if (isStyleModule) {
         const { source: compiledSource } = await (0, css_js_1.compileVanillaModule)(this.resourcePath, cssOptions.cwd ?? this.rootContext ?? process.cwd(), cssOptions.peerResolver);
@@ -43,12 +57,14 @@ function maybeTransformVanillaModule(source, options) {
     return transformVanillaModuleToEsm(source);
 }
 const pitch = function pitch() {
-    if (!hasCombinedQuery(this.resourceQuery)) {
+    if (!(0, loaderInternals_js_1.hasCombinedQuery)(this.resourceQuery)) {
         return;
     }
     const request = buildProxyRequest(this);
-    const { cssOptions } = resolveLoaderOptions(this);
-    const skipSyntheticDefault = hasNamedOnlyQueryFlag(this.resourceQuery);
+    const { cssOptions, stableNamespace: optionNamespace } = resolveLoaderOptions(this);
+    const typesRequested = (0, loaderInternals_js_1.hasQueryFlag)(this.resourceQuery, loaderInternals_js_1.TYPES_QUERY_FLAG);
+    const resolvedNamespace = (0, stableNamespace_js_1.resolveStableNamespace)(optionNamespace);
+    const skipSyntheticDefault = (0, loaderInternals_js_1.hasNamedOnlyQueryFlag)(this.resourceQuery);
     const defaultSignalPromise = skipSyntheticDefault
         ? Promise.resolve('unknown')
         : (0, moduleInfo_js_1.detectModuleDefaultExport)(this.resourcePath);
@@ -58,7 +74,18 @@ const pitch = function pitch() {
             skipSyntheticDefault,
             detection: defaultSignal,
         });
-        return createCombinedModule(request, css, { emitDefault });
+        const stableSelectorsLiteral = typesRequested
+            ? (0, stableSelectorsLiteral_js_1.buildStableSelectorsLiteral)({
+                css,
+                namespace: resolvedNamespace,
+                resourcePath: this.resourcePath,
+                emitWarning: message => emitKnightedWarning(this, message),
+            })
+            : undefined;
+        return createCombinedModule(request, css, {
+            emitDefault,
+            stableSelectorsLiteral: stableSelectorsLiteral?.literal,
+        });
     });
 };
 exports.pitch = pitch;
@@ -66,7 +93,7 @@ loader.pitch = exports.pitch;
 exports.default = loader;
 function resolveLoaderOptions(ctx) {
     const rawOptions = (typeof ctx.getOptions === 'function' ? ctx.getOptions() : {});
-    const { vanilla, ...rest } = rawOptions;
+    const { vanilla, stableNamespace, ...rest } = rawOptions;
     const cssOptions = {
         ...rest,
         cwd: rest.cwd ?? ctx.rootContext ?? process.cwd(),
@@ -74,6 +101,7 @@ function resolveLoaderOptions(ctx) {
     return {
         cssOptions,
         vanillaOptions: vanilla,
+        stableNamespace,
     };
 }
 async function extractCss(ctx, options) {
@@ -87,25 +115,12 @@ async function extractCss(ctx, options) {
 function toSourceString(source) {
     return typeof source === 'string' ? source : source.toString('utf8');
 }
-function buildInjection(css) {
-    return `\n\nexport const ${DEFAULT_EXPORT_NAME} = ${JSON.stringify(css)};\n`;
-}
-function hasCombinedQuery(query) {
-    if (!query)
-        return false;
-    const trimmed = query.startsWith('?') ? query.slice(1) : query;
-    if (!trimmed)
-        return false;
-    return trimmed
-        .split('&')
-        .filter(Boolean)
-        .some(part => (0, loaderInternals_js_1.isQueryFlag)(part, loaderInternals_js_1.COMBINED_QUERY_FLAG));
-}
-function hasNamedOnlyQueryFlag(query) {
-    if (!query)
-        return false;
-    const entries = (0, loaderInternals_js_1.splitQuery)(query);
-    return entries.some(part => loaderInternals_js_1.NAMED_ONLY_QUERY_FLAGS.some(flag => (0, loaderInternals_js_1.isQueryFlag)(part, flag)));
+function buildInjection(css, extras) {
+    const lines = [`\n\nexport const ${DEFAULT_EXPORT_NAME} = ${JSON.stringify(css)};\n`];
+    if (extras?.stableSelectorsLiteral) {
+        lines.push(extras.stableSelectorsLiteral);
+    }
+    return lines.join('');
 }
 function buildProxyRequest(ctx) {
     const sanitizedQuery = (0, loaderInternals_js_1.buildSanitizedQuery)(ctx.resourceQuery);
@@ -146,6 +161,15 @@ typeof __knightedModule.default !== 'undefined'
   ? __knightedModule.default
   : __knightedModule;`, 'export default __knightedDefault;');
     }
-    lines.push(buildInjection(css));
+    lines.push(buildInjection(css, { stableSelectorsLiteral: options?.stableSelectorsLiteral }));
     return lines.join('\n');
 }
+function emitKnightedWarning(ctx, message) {
+    const formatted = `\x1b[33m@knighted/css warning\x1b[0m ${message}`;
+    if (typeof ctx.emitWarning === 'function') {
+        ctx.emitWarning(new Error(formatted));
+        return;
+    }
+    // eslint-disable-next-line no-console
+    console.warn(formatted);
+}

package/dist/cjs/loader.d.cts

@@ -8,6 +8,7 @@ export interface KnightedCssVanillaOptions {
 }
 export interface KnightedCssLoaderOptions extends CssOptions {
     vanilla?: KnightedCssVanillaOptions;
+    stableNamespace?: string;
 }
 declare const loader: LoaderDefinitionFunction<KnightedCssLoaderOptions>;
 export declare const pitch: PitchLoaderDefinitionFunction<KnightedCssLoaderOptions>;

package/dist/cjs/loaderInternals.cjs

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.__loaderInternals = exports.NAMED_ONLY_QUERY_FLAGS = exports.COMBINED_QUERY_FLAG = void 0;
+exports.__loaderInternals = exports.NAMED_ONLY_QUERY_FLAGS = exports.TYPES_QUERY_FLAG = exports.COMBINED_QUERY_FLAG = void 0;
 exports.splitQuery = splitQuery;
 exports.isQueryFlag = isQueryFlag;
 exports.buildSanitizedQuery = buildSanitizedQuery;
+exports.hasQueryFlag = hasQueryFlag;
 exports.shouldForwardDefaultExport = shouldForwardDefaultExport;
+exports.hasCombinedQuery = hasCombinedQuery;
+exports.hasNamedOnlyQueryFlag = hasNamedOnlyQueryFlag;
+exports.determineSelectorVariant = determineSelectorVariant;
 exports.shouldEmitCombinedDefault = shouldEmitCombinedDefault;
 exports.COMBINED_QUERY_FLAG = 'combined';
+exports.TYPES_QUERY_FLAG = 'types';
 exports.NAMED_ONLY_QUERY_FLAGS = ['named-only', 'no-default'];
 function splitQuery(query) {
     const trimmed = query.startsWith('?') ? query.slice(1) : query;
@@ -33,6 +38,9 @@ function buildSanitizedQuery(query) {
         if (isQueryFlag(part, 'knighted-css')) {
             return false;
         }
+        if (isQueryFlag(part, exports.TYPES_QUERY_FLAG)) {
+            return false;
+        }
         if (exports.NAMED_ONLY_QUERY_FLAGS.some(flag => isQueryFlag(part, flag))) {
             return false;
         }
@@ -40,6 +48,22 @@ function buildSanitizedQuery(query) {
     });
     return entries.length > 0 ? `?${entries.join('&')}` : '';
 }
+function hasQueryFlag(query, flag) {
+    if (!query)
+        return false;
+    const entries = splitQuery(query);
+    if (entries.length === 0)
+        return false;
+    return entries.some(part => isQueryFlag(part, flag));
+}
+function safeDecode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
 function shouldForwardDefaultExport(request) {
     const [pathPart] = request.split('?');
     if (!pathPart)
@@ -50,6 +74,18 @@ function shouldForwardDefaultExport(request) {
     }
     return true;
 }
+function hasCombinedQuery(query) {
+    return hasQueryFlag(query, exports.COMBINED_QUERY_FLAG);
+}
+function hasNamedOnlyQueryFlag(query) {
+    return exports.NAMED_ONLY_QUERY_FLAGS.some(flag => hasQueryFlag(query, flag));
+}
+function determineSelectorVariant(query) {
+    if (hasCombinedQuery(query)) {
+        return hasNamedOnlyQueryFlag(query) ? 'combinedWithoutDefault' : 'combined';
+    }
+    return 'types';
+}
 function shouldEmitCombinedDefault(options) {
     if (options.skipSyntheticDefault) {
         return false;
@@ -68,4 +104,5 @@ function shouldEmitCombinedDefault(options) {
 exports.__loaderInternals = {
     buildSanitizedQuery,
     shouldEmitCombinedDefault,
+    determineSelectorVariant,
 };

package/dist/cjs/loaderInternals.d.cts

@@ -1,10 +1,16 @@
 import type { ModuleDefaultSignal } from './moduleInfo.cjs';
 export declare const COMBINED_QUERY_FLAG = "combined";
+export declare const TYPES_QUERY_FLAG = "types";
 export declare const NAMED_ONLY_QUERY_FLAGS: readonly ["named-only", "no-default"];
+export type SelectorTypeVariant = 'types' | 'combined' | 'combinedWithoutDefault';
 export declare function splitQuery(query: string): string[];
 export declare function isQueryFlag(entry: string, flag: string): boolean;
 export declare function buildSanitizedQuery(query?: string | null): string;
+export declare function hasQueryFlag(query: string | null | undefined, flag: string): boolean;
 export declare function shouldForwardDefaultExport(request: string): boolean;
+export declare function hasCombinedQuery(query?: string | null): boolean;
+export declare function hasNamedOnlyQueryFlag(query?: string | null): boolean;
+export declare function determineSelectorVariant(query?: string | null): SelectorTypeVariant;
 export declare function shouldEmitCombinedDefault(options: {
     detection: ModuleDefaultSignal;
     request: string;
@@ -13,4 +19,5 @@ export declare function shouldEmitCombinedDefault(options: {
 export declare const __loaderInternals: {
     buildSanitizedQuery: typeof buildSanitizedQuery;
     shouldEmitCombinedDefault: typeof shouldEmitCombinedDefault;
+    determineSelectorVariant: typeof determineSelectorVariant;
 };

package/dist/cjs/stableNamespace.cjs

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STABLE_NAMESPACE = void 0;
+exports.resolveStableNamespace = resolveStableNamespace;
+const DEFAULT_STABLE_NAMESPACE = 'knighted';
+exports.DEFAULT_STABLE_NAMESPACE = DEFAULT_STABLE_NAMESPACE;
+function resolveStableNamespace(optionNamespace) {
+    if (typeof optionNamespace === 'string') {
+        return optionNamespace;
+    }
+    return DEFAULT_STABLE_NAMESPACE;
+}

package/dist/cjs/stableNamespace.d.cts

@@ -0,0 +1,3 @@
+declare const DEFAULT_STABLE_NAMESPACE = "knighted";
+export declare function resolveStableNamespace(optionNamespace?: string): string;
+export { DEFAULT_STABLE_NAMESPACE };

package/dist/cjs/stableSelectorsLiteral.cjs

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__stableSelectorsLiteralInternals = void 0;
+exports.buildStableSelectorsLiteral = buildStableSelectorsLiteral;
+exports.collectStableSelectors = collectStableSelectors;
+exports.formatStableSelectorMap = formatStableSelectorMap;
+const lightningcss_1 = require("lightningcss");
+const helpers_js_1 = require("./helpers.cjs");
+function buildStableSelectorsLiteral(options) {
+    const trimmedNamespace = options.namespace.trim();
+    if (!trimmedNamespace) {
+        options.emitWarning(`stableSelectors requested for ${options.resourcePath} but "stableNamespace" resolved to an empty value.`);
+        return {
+            literal: 'export const stableSelectors = {} as const;\n',
+            selectorMap: new Map(),
+        };
+    }
+    const selectorMap = collectStableSelectors(options.css, trimmedNamespace, options.resourcePath);
+    if (selectorMap.size === 0) {
+        options.emitWarning(`stableSelectors requested for ${options.resourcePath} but no selectors matched namespace "${trimmedNamespace}".`);
+    }
+    return {
+        literal: `export const stableSelectors = ${formatStableSelectorMap(selectorMap)} as const;\n`,
+        selectorMap,
+    };
+}
+function collectStableSelectors(css, namespace, filename) {
+    if (!namespace)
+        return new Map();
+    const astResult = collectStableSelectorsFromAst(css, namespace, filename);
+    if (astResult) {
+        return astResult;
+    }
+    return collectStableSelectorsByRegex(css, namespace);
+}
+function collectStableSelectorsFromAst(css, namespace, filename) {
+    try {
+        const tokens = new Map();
+        const escaped = (0, helpers_js_1.escapeRegex)(namespace);
+        const pattern = new RegExp(`\\.${escaped}-([A-Za-z0-9_-]+)`, 'g');
+        (0, lightningcss_1.transform)({
+            filename: filename ?? 'knighted-types-probe.css',
+            code: Buffer.from(css),
+            minify: false,
+            visitor: {
+                Rule: {
+                    style(rule) {
+                        const target = Array.isArray(rule?.selectors)
+                            ? rule
+                            : rule?.value && Array.isArray(rule.value.selectors)
+                                ? rule.value
+                                : undefined;
+                        if (!target)
+                            return rule;
+                        for (const selector of target.selectors) {
+                            const selectorStr = (0, helpers_js_1.serializeSelector)(selector);
+                            pattern.lastIndex = 0;
+                            let match;
+                            while ((match = pattern.exec(selectorStr)) !== null) {
+                                const token = match[1];
+                                if (!token)
+                                    continue;
+                                tokens.set(token, `${namespace}-${token}`);
+                            }
+                        }
+                        return rule;
+                    },
+                },
+            },
+        });
+        return tokens;
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectStableSelectorsByRegex(css, namespace) {
+    const escaped = (0, helpers_js_1.escapeRegex)(namespace);
+    const pattern = new RegExp(`\\.${escaped}-([A-Za-z0-9_-]+)`, 'g');
+    const tokens = new Map();
+    let match;
+    while ((match = pattern.exec(css)) !== null) {
+        const token = match[1];
+        if (!token)
+            continue;
+        tokens.set(token, `${namespace}-${token}`);
+    }
+    return tokens;
+}
+function formatStableSelectorMap(map) {
+    if (map.size === 0) {
+        return 'Object.freeze({})';
+    }
+    const entries = Array.from(map.entries()).sort(([a], [b]) => a.localeCompare(b));
+    const lines = entries.map(([token, selector]) => {
+        return `  ${JSON.stringify(token)}: ${JSON.stringify(selector)}`;
+    });
+    return `Object.freeze({\n${lines.join(',\n')}\n})`;
+}
+exports.__stableSelectorsLiteralInternals = {
+    collectStableSelectors,
+    collectStableSelectorsByRegex,
+    formatStableSelectorMap,
+};

package/dist/cjs/stableSelectorsLiteral.d.cts

@@ -0,0 +1,19 @@
+export interface StableSelectorsLiteralResult {
+    literal: string;
+    selectorMap: Map<string, string>;
+}
+export declare function buildStableSelectorsLiteral(options: {
+    css: string;
+    namespace: string;
+    resourcePath: string;
+    emitWarning: (message: string) => void;
+}): StableSelectorsLiteralResult;
+export declare function collectStableSelectors(css: string, namespace: string, filename?: string): Map<string, string>;
+declare function collectStableSelectorsByRegex(css: string, namespace: string): Map<string, string>;
+export declare function formatStableSelectorMap(map: Map<string, string>): string;
+export declare const __stableSelectorsLiteralInternals: {
+    collectStableSelectors: typeof collectStableSelectors;
+    collectStableSelectorsByRegex: typeof collectStableSelectorsByRegex;
+    formatStableSelectorMap: typeof formatStableSelectorMap;
+};
+export {};

package/dist/css.js

@@ -119,14 +119,41 @@ async function compileStyleModule(file, { cwd, peerResolver, resolver, }) {
 }
 async function compileSass(filePath, indented, { cwd, peerResolver, resolver, }) {
     const sassModule = await optionalPeer('sass', 'Sass', peerResolver);
-    const sass = sassModule;
+    const sass = resolveSassNamespace(sassModule);
     const importer = createSassImporter({ cwd, resolver });
-    const result = await sass.compileAsync(filePath, {
-        style: 'expanded',
-        loadPaths: buildSassLoadPaths(filePath),
-        importers: importer ? [importer] : undefined,
+    const loadPaths = buildSassLoadPaths(filePath);
+    if (typeof sass.compileAsync === 'function') {
+        const result = await sass.compileAsync(filePath, {
+            style: 'expanded',
+            loadPaths,
+            importers: importer ? [importer] : undefined,
+        });
+        return result.css;
+    }
+    if (typeof sass.render === 'function') {
+        return renderLegacySass(sass, filePath, indented, loadPaths);
+    }
+    throw new Error('@knighted/css: Installed "sass" package does not expose compileAsync or render APIs. Please update "sass" to a supported version.');
+}
+function renderLegacySass(sass, filePath, indented, loadPaths) {
+    return new Promise((resolve, reject) => {
+        sass.render({
+            file: filePath,
+            indentedSyntax: indented,
+            outputStyle: 'expanded',
+            includePaths: loadPaths,
+        }, (error, result) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            if (!result || typeof result.css === 'undefined') {
+                resolve('');
+                return;
+            }
+            resolve(result.css.toString());
+        });
     });
-    return result.css;
 }
 // Ensure Sass can resolve bare module specifiers by walking node_modules folders.
 function buildSassLoadPaths(filePath) {
@@ -214,6 +241,27 @@ async function optionalPeer(name, label, loader) {
         throw error;
     }
 }
+function resolveSassNamespace(mod) {
+    if (isSassNamespace(mod)) {
+        return mod;
+    }
+    if (typeof mod === 'object' &&
+        mod !== null &&
+        'default' in mod) {
+        const candidate = mod.default;
+        if (isSassNamespace(candidate)) {
+            return candidate;
+        }
+    }
+    return mod;
+}
+function isSassNamespace(candidate) {
+    if (typeof candidate !== 'object' || !candidate) {
+        return false;
+    }
+    const namespace = candidate;
+    return typeof namespace.compile === 'function' || typeof namespace.render === 'function';
+}
 function unwrapModuleNamespace(mod) {
     if (typeof mod === 'object' &&
         mod !== null &&

package/dist/generateTypes.d.ts

@@ -0,0 +1,54 @@
+import { type SelectorTypeVariant } from './loaderInternals.js';
+interface DeclarationRecord {
+    specifier: string;
+    filePath: string;
+}
+export interface GenerateTypesResult {
+    written: number;
+    removed: number;
+    declarations: DeclarationRecord[];
+    warnings: string[];
+    outDir: string;
+    typesIndexPath: string;
+}
+export interface GenerateTypesOptions {
+    rootDir?: string;
+    include?: string[];
+    outDir?: string;
+    typesRoot?: string;
+    stableNamespace?: string;
+}
+export declare function generateTypes(options?: GenerateTypesOptions): Promise<GenerateTypesResult>;
+declare function normalizeIncludeOptions(include: string[] | undefined, rootDir: string): string[];
+declare function stripInlineLoader(specifier: string): string;
+declare function splitResourceAndQuery(specifier: string): {
+    resource: string;
+    query: string;
+};
+declare function buildDeclarationFileName(specifier: string): string;
+declare function formatModuleDeclaration(specifier: string, variant: SelectorTypeVariant, selectors: Map<string, string>): string;
+declare function formatSelectorType(selectors: Map<string, string>): string;
+export declare function runGenerateTypesCli(argv?: string[]): Promise<void>;
+export interface ParsedCliArgs {
+    rootDir: string;
+    include?: string[];
+    outDir?: string;
+    typesRoot?: string;
+    stableNamespace?: string;
+    help?: boolean;
+}
+declare function parseCliArgs(argv: string[]): ParsedCliArgs;
+declare function printHelp(): void;
+declare function reportCliResult(result: GenerateTypesResult): void;
+export declare const __generateTypesInternals: {
+    stripInlineLoader: typeof stripInlineLoader;
+    splitResourceAndQuery: typeof splitResourceAndQuery;
+    buildDeclarationFileName: typeof buildDeclarationFileName;
+    formatModuleDeclaration: typeof formatModuleDeclaration;
+    formatSelectorType: typeof formatSelectorType;
+    normalizeIncludeOptions: typeof normalizeIncludeOptions;
+    parseCliArgs: typeof parseCliArgs;
+    printHelp: typeof printHelp;
+    reportCliResult: typeof reportCliResult;
+};
+export {};