@knighted/css 1.0.0-rc.3 → 1.0.0-rc.5

package/dist/cjs/css.cjs

@@ -9,6 +9,7 @@ exports.cssWithMeta = cssWithMeta;
 exports.compileVanillaModule = compileVanillaModule;
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = require("node:fs");
+const node_url_1 = require("node:url");
 const dependency_tree_1 = __importDefault(require("dependency-tree"));
 const lightningcss_1 = require("lightningcss");
 const helpers_js_1 = require("./helpers.cjs");
@@ -35,6 +36,7 @@ async function cssWithMeta(entry, options = {}) {
         const chunk = await compileStyleModule(file, {
             cwd,
             peerResolver: options.peerResolver,
+            resolver: options.resolver,
         });
         if (chunk) {
             chunks.push(chunk);
@@ -105,13 +107,17 @@ function matchExtension(filePath, extensions) {
     const lower = filePath.toLowerCase();
     return extensions.find(ext => lower.endsWith(ext));
 }
-async function compileStyleModule(file, { cwd, peerResolver }) {
+async function compileStyleModule(file, { cwd, peerResolver, resolver, }) {
     switch (file.ext) {
         case '.css':
             return node_fs_1.promises.readFile(file.path, 'utf8');
         case '.scss':
         case '.sass':
-            return compileSass(file.path, file.ext === '.sass', peerResolver);
+            return compileSass(file.path, file.ext === '.sass', {
+                cwd,
+                peerResolver,
+                resolver,
+            });
         case '.less':
             return compileLess(file.path, peerResolver);
         case '.css.ts':
@@ -120,14 +126,145 @@ async function compileStyleModule(file, { cwd, peerResolver }) {
             return '';
     }
 }
-async function compileSass(filePath, indented, peerResolver) {
+async function compileSass(filePath, indented, { cwd, peerResolver, resolver, }) {
     const sassModule = await optionalPeer('sass', 'Sass', peerResolver);
     const sass = sassModule;
-    const result = sass.compile(filePath, {
+    const importer = createSassImporter({ cwd, resolver });
+    const result = await sass.compileAsync(filePath, {
         style: 'expanded',
+        loadPaths: buildSassLoadPaths(filePath),
+        importers: importer ? [importer] : undefined,
     });
     return result.css;
 }
+// Ensure Sass can resolve bare module specifiers by walking node_modules folders.
+function buildSassLoadPaths(filePath) {
+    const loadPaths = new Set();
+    let cursor = node_path_1.default.dirname(filePath);
+    const root = node_path_1.default.parse(cursor).root;
+    while (true) {
+        loadPaths.add(cursor);
+        loadPaths.add(node_path_1.default.join(cursor, 'node_modules'));
+        if (cursor === root)
+            break;
+        cursor = node_path_1.default.dirname(cursor);
+    }
+    const cwd = process.cwd();
+    loadPaths.add(cwd);
+    loadPaths.add(node_path_1.default.join(cwd, 'node_modules'));
+    return Array.from(loadPaths).filter(dir => dir && (0, node_fs_1.existsSync)(dir));
+}
+function createSassImporter({ cwd, resolver }) {
+    if (!resolver)
+        return undefined;
+    const debug = process.env.KNIGHTED_CSS_DEBUG_SASS === '1';
+    return {
+        async canonicalize(url, context) {
+            if (debug) {
+                console.error('[knighted-css:sass] canonicalize request:', url);
+                if (context?.containingUrl) {
+                    console.error('[knighted-css:sass] containing url:', context.containingUrl.href);
+                }
+            }
+            if (shouldNormalizeSpecifier(url)) {
+                const resolvedPath = await resolveAliasSpecifier(url, resolver, cwd);
+                if (!resolvedPath) {
+                    if (debug) {
+                        console.error('[knighted-css:sass] resolver returned no result for', url);
+                    }
+                    return null;
+                }
+                const fileUrl = (0, node_url_1.pathToFileURL)(resolvedPath);
+                if (debug) {
+                    console.error('[knighted-css:sass] canonical url:', fileUrl.href);
+                }
+                return fileUrl;
+            }
+            const relativePath = resolveRelativeSpecifier(url, context?.containingUrl);
+            if (relativePath) {
+                const fileUrl = (0, node_url_1.pathToFileURL)(relativePath);
+                if (debug) {
+                    console.error('[knighted-css:sass] canonical url:', fileUrl.href);
+                }
+                return fileUrl;
+            }
+            return null;
+        },
+        async load(canonicalUrl) {
+            if (debug) {
+                console.error('[knighted-css:sass] load request:', canonicalUrl.href);
+            }
+            const filePath = (0, node_url_1.fileURLToPath)(canonicalUrl);
+            const contents = await node_fs_1.promises.readFile(filePath, 'utf8');
+            return {
+                contents,
+                syntax: inferSassSyntax(filePath),
+            };
+        },
+    };
+}
+async function resolveAliasSpecifier(specifier, resolver, cwd) {
+    const resolved = await resolver(specifier, { cwd });
+    if (!resolved) {
+        return undefined;
+    }
+    if (resolved.startsWith('file://')) {
+        return ensureSassPath((0, node_url_1.fileURLToPath)(new URL(resolved)));
+    }
+    const normalized = node_path_1.default.isAbsolute(resolved) ? resolved : node_path_1.default.resolve(cwd, resolved);
+    return ensureSassPath(normalized);
+}
+function shouldNormalizeSpecifier(specifier) {
+    const schemeMatch = specifier.match(/^([a-z][\w+.-]*):/i);
+    if (!schemeMatch) {
+        return false;
+    }
+    const scheme = schemeMatch[1].toLowerCase();
+    if (scheme === 'file' ||
+        scheme === 'http' ||
+        scheme === 'https' ||
+        scheme === 'data' ||
+        scheme === 'sass') {
+        return false;
+    }
+    return true;
+}
+function inferSassSyntax(filePath) {
+    return filePath.endsWith('.sass') ? 'indented' : 'scss';
+}
+function ensureSassPath(filePath) {
+    if ((0, node_fs_1.existsSync)(filePath)) {
+        return filePath;
+    }
+    const ext = node_path_1.default.extname(filePath);
+    const dir = node_path_1.default.dirname(filePath);
+    const base = node_path_1.default.basename(filePath, ext);
+    const partialCandidate = node_path_1.default.join(dir, `_${base}${ext}`);
+    if (ext && (0, node_fs_1.existsSync)(partialCandidate)) {
+        return partialCandidate;
+    }
+    const indexCandidate = node_path_1.default.join(dir, base, `index${ext}`);
+    if (ext && (0, node_fs_1.existsSync)(indexCandidate)) {
+        return indexCandidate;
+    }
+    const partialIndexCandidate = node_path_1.default.join(dir, base, `_index${ext}`);
+    if (ext && (0, node_fs_1.existsSync)(partialIndexCandidate)) {
+        return partialIndexCandidate;
+    }
+    return undefined;
+}
+function resolveRelativeSpecifier(specifier, containingUrl) {
+    if (!containingUrl || containingUrl.protocol !== 'file:') {
+        return undefined;
+    }
+    if (/^[a-z][\w+.-]*:/i.test(specifier)) {
+        return undefined;
+    }
+    const containingPath = (0, node_url_1.fileURLToPath)(containingUrl);
+    const baseDir = node_path_1.default.dirname(containingPath);
+    const candidate = node_path_1.default.resolve(baseDir, specifier);
+    return ensureSassPath(candidate);
+}
 async function compileLess(filePath, peerResolver) {
     const mod = await optionalPeer('less', 'Less', peerResolver);
     const less = unwrapModuleNamespace(mod);

package/dist/cjs/stableSelectors.cjs

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableClassFromModule = void 0;
+exports.stableToken = stableToken;
+exports.stableClass = stableClass;
+exports.stableSelector = stableSelector;
+exports.createStableClassFactory = createStableClassFactory;
+exports.stableClassName = stableClassName;
+const DEFAULT_NAMESPACE = 'knighted';
+const defaultJoin = (values) => values.filter(Boolean).join(' ');
+const normalizeToken = (token) => {
+    const sanitized = token
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/[^A-Za-z0-9_-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return sanitized.length ? sanitized : 'stable';
+};
+function stableToken(token, options) {
+    const normalized = normalizeToken(token);
+    const namespace = options?.namespace?.trim() ?? DEFAULT_NAMESPACE;
+    if (!namespace) {
+        return normalized;
+    }
+    return `${namespace}-${normalized}`;
+}
+function stableClass(token, options) {
+    return stableToken(token, options);
+}
+function stableSelector(token, options) {
+    return `.${stableToken(token, options)}`;
+}
+function createStableClassFactory(options) {
+    return (token) => stableClass(token, options);
+}
+function stableClassName(styles, key, options) {
+    const hashed = styles[key] ?? '';
+    const token = options?.token ?? String(key);
+    const stable = stableClass(token, options);
+    const join = options?.join ?? defaultJoin;
+    return join([hashed, stable]);
+}
+exports.stableClassFromModule = stableClassName;

package/dist/cjs/stableSelectors.d.cts

@@ -0,0 +1,13 @@
+export interface StableSelectorOptions {
+    namespace?: string;
+}
+export interface StableClassNameOptions extends StableSelectorOptions {
+    token?: string;
+    join?: (values: string[]) => string;
+}
+export declare function stableToken(token: string, options?: StableSelectorOptions): string;
+export declare function stableClass(token: string, options?: StableSelectorOptions): string;
+export declare function stableSelector(token: string, options?: StableSelectorOptions): string;
+export declare function createStableClassFactory(options?: StableSelectorOptions): (token: string) => string;
+export declare function stableClassName<T extends Record<string, string>>(styles: T, key: keyof T | string, options?: StableClassNameOptions): string;
+export declare const stableClassFromModule: typeof stableClassName;

package/dist/css.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
-import { promises as fs } from 'node:fs';
+import { existsSync, promises as fs } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import dependencyTree from 'dependency-tree';
 import { composeVisitors, transform as lightningTransform, } from 'lightningcss';
 import { applyStringSpecificityBoost, buildSpecificityVisitor, } from './helpers.js';
@@ -26,6 +27,7 @@ export async function cssWithMeta(entry, options = {}) {
         const chunk = await compileStyleModule(file, {
             cwd,
             peerResolver: options.peerResolver,
+            resolver: options.resolver,
         });
         if (chunk) {
             chunks.push(chunk);
@@ -96,13 +98,17 @@ function matchExtension(filePath, extensions) {
     const lower = filePath.toLowerCase();
     return extensions.find(ext => lower.endsWith(ext));
 }
-async function compileStyleModule(file, { cwd, peerResolver }) {
+async function compileStyleModule(file, { cwd, peerResolver, resolver, }) {
     switch (file.ext) {
         case '.css':
             return fs.readFile(file.path, 'utf8');
         case '.scss':
         case '.sass':
-            return compileSass(file.path, file.ext === '.sass', peerResolver);
+            return compileSass(file.path, file.ext === '.sass', {
+                cwd,
+                peerResolver,
+                resolver,
+            });
         case '.less':
             return compileLess(file.path, peerResolver);
         case '.css.ts':
@@ -111,14 +117,145 @@ async function compileStyleModule(file, { cwd, peerResolver }) {
             return '';
     }
 }
-async function compileSass(filePath, indented, peerResolver) {
+async function compileSass(filePath, indented, { cwd, peerResolver, resolver, }) {
     const sassModule = await optionalPeer('sass', 'Sass', peerResolver);
     const sass = sassModule;
-    const result = sass.compile(filePath, {
+    const importer = createSassImporter({ cwd, resolver });
+    const result = await sass.compileAsync(filePath, {
         style: 'expanded',
+        loadPaths: buildSassLoadPaths(filePath),
+        importers: importer ? [importer] : undefined,
     });
     return result.css;
 }
+// Ensure Sass can resolve bare module specifiers by walking node_modules folders.
+function buildSassLoadPaths(filePath) {
+    const loadPaths = new Set();
+    let cursor = path.dirname(filePath);
+    const root = path.parse(cursor).root;
+    while (true) {
+        loadPaths.add(cursor);
+        loadPaths.add(path.join(cursor, 'node_modules'));
+        if (cursor === root)
+            break;
+        cursor = path.dirname(cursor);
+    }
+    const cwd = process.cwd();
+    loadPaths.add(cwd);
+    loadPaths.add(path.join(cwd, 'node_modules'));
+    return Array.from(loadPaths).filter(dir => dir && existsSync(dir));
+}
+function createSassImporter({ cwd, resolver }) {
+    if (!resolver)
+        return undefined;
+    const debug = process.env.KNIGHTED_CSS_DEBUG_SASS === '1';
+    return {
+        async canonicalize(url, context) {
+            if (debug) {
+                console.error('[knighted-css:sass] canonicalize request:', url);
+                if (context?.containingUrl) {
+                    console.error('[knighted-css:sass] containing url:', context.containingUrl.href);
+                }
+            }
+            if (shouldNormalizeSpecifier(url)) {
+                const resolvedPath = await resolveAliasSpecifier(url, resolver, cwd);
+                if (!resolvedPath) {
+                    if (debug) {
+                        console.error('[knighted-css:sass] resolver returned no result for', url);
+                    }
+                    return null;
+                }
+                const fileUrl = pathToFileURL(resolvedPath);
+                if (debug) {
+                    console.error('[knighted-css:sass] canonical url:', fileUrl.href);
+                }
+                return fileUrl;
+            }
+            const relativePath = resolveRelativeSpecifier(url, context?.containingUrl);
+            if (relativePath) {
+                const fileUrl = pathToFileURL(relativePath);
+                if (debug) {
+                    console.error('[knighted-css:sass] canonical url:', fileUrl.href);
+                }
+                return fileUrl;
+            }
+            return null;
+        },
+        async load(canonicalUrl) {
+            if (debug) {
+                console.error('[knighted-css:sass] load request:', canonicalUrl.href);
+            }
+            const filePath = fileURLToPath(canonicalUrl);
+            const contents = await fs.readFile(filePath, 'utf8');
+            return {
+                contents,
+                syntax: inferSassSyntax(filePath),
+            };
+        },
+    };
+}
+async function resolveAliasSpecifier(specifier, resolver, cwd) {
+    const resolved = await resolver(specifier, { cwd });
+    if (!resolved) {
+        return undefined;
+    }
+    if (resolved.startsWith('file://')) {
+        return ensureSassPath(fileURLToPath(new URL(resolved)));
+    }
+    const normalized = path.isAbsolute(resolved) ? resolved : path.resolve(cwd, resolved);
+    return ensureSassPath(normalized);
+}
+function shouldNormalizeSpecifier(specifier) {
+    const schemeMatch = specifier.match(/^([a-z][\w+.-]*):/i);
+    if (!schemeMatch) {
+        return false;
+    }
+    const scheme = schemeMatch[1].toLowerCase();
+    if (scheme === 'file' ||
+        scheme === 'http' ||
+        scheme === 'https' ||
+        scheme === 'data' ||
+        scheme === 'sass') {
+        return false;
+    }
+    return true;
+}
+function inferSassSyntax(filePath) {
+    return filePath.endsWith('.sass') ? 'indented' : 'scss';
+}
+function ensureSassPath(filePath) {
+    if (existsSync(filePath)) {
+        return filePath;
+    }
+    const ext = path.extname(filePath);
+    const dir = path.dirname(filePath);
+    const base = path.basename(filePath, ext);
+    const partialCandidate = path.join(dir, `_${base}${ext}`);
+    if (ext && existsSync(partialCandidate)) {
+        return partialCandidate;
+    }
+    const indexCandidate = path.join(dir, base, `index${ext}`);
+    if (ext && existsSync(indexCandidate)) {
+        return indexCandidate;
+    }
+    const partialIndexCandidate = path.join(dir, base, `_index${ext}`);
+    if (ext && existsSync(partialIndexCandidate)) {
+        return partialIndexCandidate;
+    }
+    return undefined;
+}
+function resolveRelativeSpecifier(specifier, containingUrl) {
+    if (!containingUrl || containingUrl.protocol !== 'file:') {
+        return undefined;
+    }
+    if (/^[a-z][\w+.-]*:/i.test(specifier)) {
+        return undefined;
+    }
+    const containingPath = fileURLToPath(containingUrl);
+    const baseDir = path.dirname(containingPath);
+    const candidate = path.resolve(baseDir, specifier);
+    return ensureSassPath(candidate);
+}
 async function compileLess(filePath, peerResolver) {
     const mod = await optionalPeer('less', 'Less', peerResolver);
     const less = unwrapModuleNamespace(mod);

package/dist/stableSelectors.d.ts

@@ -0,0 +1,13 @@
+export interface StableSelectorOptions {
+    namespace?: string;
+}
+export interface StableClassNameOptions extends StableSelectorOptions {
+    token?: string;
+    join?: (values: string[]) => string;
+}
+export declare function stableToken(token: string, options?: StableSelectorOptions): string;
+export declare function stableClass(token: string, options?: StableSelectorOptions): string;
+export declare function stableSelector(token: string, options?: StableSelectorOptions): string;
+export declare function createStableClassFactory(options?: StableSelectorOptions): (token: string) => string;
+export declare function stableClassName<T extends Record<string, string>>(styles: T, key: keyof T | string, options?: StableClassNameOptions): string;
+export declare const stableClassFromModule: typeof stableClassName;

package/dist/stableSelectors.js

@@ -0,0 +1,36 @@
+const DEFAULT_NAMESPACE = 'knighted';
+const defaultJoin = (values) => values.filter(Boolean).join(' ');
+const normalizeToken = (token) => {
+    const sanitized = token
+        .trim()
+        .replace(/\s+/g, '-')
+        .replace(/[^A-Za-z0-9_-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return sanitized.length ? sanitized : 'stable';
+};
+export function stableToken(token, options) {
+    const normalized = normalizeToken(token);
+    const namespace = options?.namespace?.trim() ?? DEFAULT_NAMESPACE;
+    if (!namespace) {
+        return normalized;
+    }
+    return `${namespace}-${normalized}`;
+}
+export function stableClass(token, options) {
+    return stableToken(token, options);
+}
+export function stableSelector(token, options) {
+    return `.${stableToken(token, options)}`;
+}
+export function createStableClassFactory(options) {
+    return (token) => stableClass(token, options);
+}
+export function stableClassName(styles, key, options) {
+    const hashed = styles[key] ?? '';
+    const token = options?.token ?? String(key);
+    const stable = stableClass(token, options);
+    const join = options?.join ?? defaultJoin;
+    return join([hashed, stable]);
+}
+export const stableClassFromModule = stableClassName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.0-rc.3",
+  "version": "1.0.0-rc.5",
   "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",
@@ -32,6 +32,18 @@
     "./loader-queries": {
       "types": "./loader-queries.d.ts",
       "default": "./loader-queries.d.ts"
+    },
+    "./stableSelectors": {
+      "types": "./dist/stableSelectors.d.ts",
+      "import": "./dist/stableSelectors.js",
+      "require": "./dist/cjs/stableSelectors.cjs"
+    },
+    "./stable": {
+      "sass": "./stable/_index.scss",
+      "default": "./stable/_index.scss"
+    },
+    "./stable/stable.css": {
+      "default": "./stable/stable.css"
     }
   },
   "keywords": [
@@ -80,7 +92,8 @@
   "files": [
     "dist",
     "loader-queries.d.ts",
-    "types.d.ts"
+    "types.d.ts",
+    "stable"
   ],
   "author": "KCM <knightedcodemonkey@gmail.com>",
   "license": "MIT",

package/stable/_index.scss

@@ -0,0 +1,57 @@
+// Knighted stable selector mixins
+// Usage: @use '@knighted/css/stable' as knighted;
+//        .button { @include knighted.stable('button') { ... } }
+
+@use 'sass:meta';
+
+$knighted-stable-namespace: 'knighted' !default;
+
+@function _knighted-normalize-token($token) {
+  @if meta.type-of($token) == 'number' {
+    @return $token;
+  }
+  @return $token;
+}
+
+@function stable-token($token, $namespace: $knighted-stable-namespace) {
+  $normalized-token: _knighted-normalize-token($token);
+  @if $namespace == '' {
+    @return $normalized-token;
+  }
+  @return '#{$namespace}-#{$normalized-token}';
+}
+
+@function stable-class($token, $namespace: $knighted-stable-namespace) {
+  $token-value: stable-token($token, $namespace);
+  @return '.#{$token-value}';
+}
+
+@mixin stable($token, $namespace: $knighted-stable-namespace) {
+  @if not & {
+    @error 'The knighted.stable mixin must be used within a selector context so that "&" is defined.';
+  }
+
+  $stable-selector: stable-class($token, $namespace);
+  @at-root #{&},
+    #{$stable-selector} {
+    @content;
+  }
+}
+
+@mixin stable-at-root($selector, $token, $namespace: $knighted-stable-namespace) {
+  $stable-selector: stable-class($token, $namespace);
+  @at-root #{$selector},
+    #{$stable-selector} {
+    @content;
+  }
+}
+
+@function stable-class-name($token, $namespace: $knighted-stable-namespace) {
+  @return stable-token($token, $namespace);
+}
+
+@mixin stable-only($token, $namespace: $knighted-stable-namespace) {
+  @at-root #{stable-class($token, $namespace)} {
+    @content;
+  }
+}

package/stable/stable.css

@@ -0,0 +1,15 @@
+@layer knighted.stable;
+
+:root {
+  --knighted-stable-namespace: 'knighted';
+}
+
+/*
+Usage:
+  @import '@knighted/css/stable/stable.css';
+  @layer knighted.stable {
+    .knighted-button {
+      declarations go here;
+    }
+  }
+*/