@knighted/css 1.0.0-rc.0 → 1.0.0-rc.10

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/dist/stableSelectorsLiteral.d.ts

@@ -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/stableSelectorsLiteral.js

@@ -0,0 +1,98 @@
+import { transform as lightningTransform } from 'lightningcss';
+import { escapeRegex, serializeSelector } from './helpers.js';
+export 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,
+    };
+}
+export 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 = escapeRegex(namespace);
+        const pattern = new RegExp(`\\.${escaped}-([A-Za-z0-9_-]+)`, 'g');
+        lightningTransform({
+            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 = 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 = 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;
+}
+export 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})`;
+}
+export const __stableSelectorsLiteralInternals = {
+    collectStableSelectors,
+    collectStableSelectorsByRegex,
+    formatStableSelectorMap,
+};

package/dist/types.d.ts

@@ -0,0 +1,4 @@
+export type CssResolver = (specifier: string, ctx: {
+    cwd: string;
+    from?: string;
+}) => string | Promise<string | undefined>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/loader-queries.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Ambient declaration for loader query imports like "./file.js?knighted-css".
+ * The loader appends a named export `knightedCss` containing the compiled CSS.
+ */
+declare module '*?knighted-css' {
+  export const knightedCss: string
+}
+
+type KnightedCssStableSelectorMap = Readonly<Record<string, string>>
+
+declare module '*?knighted-css&types' {
+  export const knightedCss: string
+  export const stableSelectors: KnightedCssStableSelectorMap
+}
+
+/**
+ * Ambient declaration for combined loader imports (e.g. "./file.tsx?knighted-css&combined").
+ * These modules behave like the original module with an additional `knightedCss` export.
+ * TypeScript cannot infer the underlying module automatically, so consumers can
+ * import the default export and narrow it with `KnightedCssCombinedModule<typeof import('./file')>`.
+ */
+type KnightedCssCombinedModule<TModule> = TModule & { knightedCss: string }
+
+declare module '*?knighted-css&combined' {
+  const combined: KnightedCssCombinedModule<Record<string, unknown>>
+  export default combined
+  export const knightedCss: string
+}
+
+declare module '*?knighted-css&combined&named-only' {
+  const combined: KnightedCssCombinedModule<Record<string, unknown>>
+  export default combined
+  export const knightedCss: string
+}
+
+declare module '*?knighted-css&combined&no-default' {
+  const combined: KnightedCssCombinedModule<Record<string, unknown>>
+  export default combined
+  export const knightedCss: string
+}
+
+declare module '*?knighted-css&combined&types' {
+  const combined: KnightedCssCombinedModule<Record<string, unknown>>
+  export default combined
+  export const knightedCss: string
+  export const stableSelectors: KnightedCssStableSelectorMap
+}
+
+declare module '*?knighted-css&combined&named-only&types' {
+  const combined: KnightedCssCombinedModule<Record<string, unknown>>
+  export default combined
+  export const knightedCss: string
+  export const stableSelectors: KnightedCssStableSelectorMap
+}
+
+declare module '*?knighted-css&combined&no-default&types' {
+  const combined: KnightedCssCombinedModule<Record<string, unknown>>
+  export default combined
+  export const knightedCss: string
+  export const stableSelectors: KnightedCssStableSelectorMap
+}

package/package.json

@@ -1,13 +1,29 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.10",
   "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",
-  "types": "./dist/css.d.ts",
+  "types": "./types.d.ts",
+  "typesVersions": {
+    "*": {
+      "loader": [
+        "./dist/loader.d.ts"
+      ],
+      "loader-queries": [
+        "./loader-queries.d.ts"
+      ],
+      "generate-types": [
+        "./dist/generateTypes.d.ts"
+      ],
+      "*": [
+        "./types.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
-      "types": "./dist/css.d.ts",
+      "types": "./types.d.ts",
       "import": "./dist/css.js",
       "require": "./dist/cjs/css.cjs"
     },
@@ -15,6 +31,27 @@
       "types": "./dist/loader.d.ts",
       "import": "./dist/loader.js",
       "require": "./dist/cjs/loader.cjs"
+    },
+    "./loader-queries": {
+      "types": "./loader-queries.d.ts",
+      "default": "./loader-queries.d.ts"
+    },
+    "./generate-types": {
+      "types": "./dist/generateTypes.d.ts",
+      "import": "./dist/generateTypes.js",
+      "default": "./dist/generateTypes.js"
+    },
+    "./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": [
@@ -29,15 +66,23 @@
     "vanilla-extract",
     "lightningcss"
   ],
+  "bin": {
+    "knighted-css-generate-types": "./bin/generate-types.js"
+  },
   "scripts": {
-    "build": "duel",
-    "check-types": "tsc --noEmit",
+    "build": "duel && node ./scripts/copy-types-stub.js",
+    "check-types": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.tests.json",
     "test": "c8 --reporter=text --reporter=text-summary --reporter=lcov --include \"src/**/*.ts\" tsx --test test/**/*.test.ts",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "dependency-tree": "^11.2.0",
-    "lightningcss": "^1.30.2"
+    "es-module-lexer": "^2.0.0",
+    "lightningcss": "^1.30.2",
+    "node-module-type": "^1.0.1",
+    "get-tsconfig": "^4.13.0",
+    "oxc-parser": "^0.104.0",
+    "oxc-resolver": "^11.16.0",
+    "tsconfig-paths": "^4.2.0"
   },
   "peerDependencies": {
     "@vanilla-extract/integration": "^8.0.0",
@@ -56,7 +101,12 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "loader-queries.d.ts",
+    "types.d.ts",
+    "stable",
+    "bin",
+    "types-stub"
   ],
   "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;
+    }
+  }
+*/

package/types-stub/index.d.ts

@@ -0,0 +1,5 @@
+// Placeholder stub for @knighted/css stable selector declarations.
+// Running `knighted-css-generate-types` replaces this file with project-specific
+// references into the generated `.knighted-css` manifest.
+
+export {}

package/types.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="./loader-queries.d.ts" />
+/// <reference path="./types-stub/index.d.ts" />
+
+export * from './dist/css.js'