@symbiote-native/css-parser 0.2.3 → 0.4.0

package/typescript-plugin.cjs

@@ -8,10 +8,10 @@
 // separate, on-disk source of truth for `tsc`/`vue-tsc` CLI runs — plugins never load there.
 //
 // Core mechanism: override getScriptSnapshot + resolveModuleNameLiterals to synthesize a virtual
-// .d.ts for the import. Two things worth calling out: (1) the class extractor converts kebab-case
-// to camelCase, so a suggested key like `section-tight` matches the ACTUAL exported key our
-// runtime produces (@symbiote-native/css-parser's parseCSS always camelCases — see
-// src/generate-dts.ts's classNamesToDtsSource, which this plugin's dts shape mirrors); (2) the dts
+// .d.ts for the import. Two things worth calling out: (1) the class extractor keeps the AUTHORED
+// spelling, because that is the key the runtime export map carries — see
+// src/generate-dts/index.ts's classNamesToDtsSource, which this plugin's dts shape mirrors, and
+// which quotes a non-identifier key for the same reason; (2) the dts
 // cache is keyed on the file's mtime, so autocomplete doesn't go stale after editing the CSS file
 // and wait for the IDE to restart tsserver.
 //
@@ -21,22 +21,20 @@
 // a correct, non-approximated preprocessor pipeline can't run here today. Those files still get
 // basic (non-literal) type coverage from the project's ambient `.css` fallback declaration and
 // from `css-dts`'s on-disk generation at pretypecheck time — just without live per-class
-// completion in the plugin. A real follow-up, not a silent gap: recorded here, not hidden.
+// completion in the plugin.
 //
 // SCOPE, second cut: only a SIMPLE `.foo { ... }` class selector is recognized correctly — a
-// compound (`.btn.primary`) or descendant (`.card .title`) selector, which the real
-// src/parser.ts's extractClassName merges into ONE key (`btnPrimary`/`cardTitle`), gets
-// extracted here as TWO separate (wrong, non-existent) keys instead. This is an accepted
-// limitation of the regex-based approach — complex selectors may not be detected correctly.
+// compound (`.btn.primary`) or descendant (`.card .title`) selector is extracted here as TWO
+// separate keys, where the real compiler keeps the tokens together on one rule and exports only
+// the names the author actually wrote.
 //
 // Hand-written plain CommonJS, NOT compiled from a `.ts`/`.cts` source — same convention already
 // used for each adapter's metro-css-parser.cjs shim. tsserver loads a plugin via a synchronous
 // `require()`, which cannot load this package's own ESM build output; a `.cts` source was tried
-// first and rejected because
-// this package's shared tsconfig (`moduleResolution: "Bundler"`, needed for the rest of the
-// package) doesn't apply the classic .cts→CJS format-forcing TypeScript otherwise gives Node16/
-// NodeNext projects — carving out a second tsconfig/project reference just for one file was more
-// machinery than a ~150-line, dependency-free plugin warrants.
+// first and rejected because this package's shared tsconfig (`moduleResolution: "Bundler"`,
+// needed for the rest of the package) doesn't apply the classic .cts→CJS format-forcing
+// TypeScript otherwise gives Node16/NodeNext projects — carving out a second tsconfig/project
+// reference just for one file was more machinery than a ~150-line, dependency-free plugin warrants.
 'use strict';
 
 const fs = require('node:fs');
@@ -48,17 +46,19 @@ function isCssModuleFile(fileName) {
   return CSS_MODULE_RE.test(fileName);
 }
 
-function kebabToCamel(value) {
-  return value.replace(/-([a-z0-9])/gi, (_match, char) => char.toUpperCase());
-}
-
+// Names come out AS AUTHORED — `.section-tight` stays `section-tight`, read as
+// `styles['section-tight']`. This must track `compileCssModule`'s export map exactly: the editor
+// offering a key the runtime does not carry is the one failure this plugin can produce, and it
+// fails in both directions at once (a suggested `sectionTight` is `undefined` at runtime, while
+// the real `styles['section-tight']` reads as a TS2339). `generateDts` quotes a key that is not a
+// valid identifier, which is what makes the kebab spelling usable.
 function extractClassNames(css) {
   const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
   const names = new Set();
   const classRe = /\.([a-zA-Z_][\w-]*)/g;
   let match;
   while ((match = classRe.exec(withoutComments))) {
-    names.add(kebabToCamel(match[1]));
+    names.add(match[1]);
   }
   return [...names];
 }
@@ -70,7 +70,7 @@ function generateDts(classNames) {
 
   const fields = [...classNames]
     .sort()
-    .map((name) => {
+    .map(name => {
       const key = IDENTIFIER_RE.test(name) ? name : JSON.stringify(name);
       return `  readonly ${key}: string;`;
     })
@@ -114,16 +114,20 @@ function init(modules) {
       return dts;
     }
 
-    const originalGetScriptKind = host.getScriptKind ? host.getScriptKind.bind(host) : undefined;
+    const originalGetScriptKind = host.getScriptKind
+      ? host.getScriptKind.bind(host)
+      : undefined;
     const originalGetScriptSnapshot = host.getScriptSnapshot.bind(host);
     const originalResolveModuleNameLiterals = host.resolveModuleNameLiterals;
 
-    host.getScriptKind = (fileName) =>
+    host.getScriptKind = fileName =>
       isCssModuleFile(fileName)
         ? typescript.ScriptKind.TS
-        : (originalGetScriptKind ? originalGetScriptKind(fileName) : typescript.ScriptKind.Unknown);
+        : originalGetScriptKind
+          ? originalGetScriptKind(fileName)
+          : typescript.ScriptKind.Unknown;
 
-    host.getScriptSnapshot = (fileName) =>
+    host.getScriptSnapshot = fileName =>
       isCssModuleFile(fileName)
         ? typescript.ScriptSnapshot.fromString(getDtsForCssFile(fileName))
         : originalGetScriptSnapshot(fileName);
@@ -150,7 +154,10 @@ function init(modules) {
         return literals.map((literal, index) => {
           const moduleName = literal.text;
           if (isCssModuleFile(moduleName) && moduleName.startsWith('.')) {
-            const resolvedPath = resolveRelativePath(moduleName, containingFile);
+            const resolvedPath = resolveRelativePath(
+              moduleName,
+              containingFile,
+            );
             if (host.fileExists && host.fileExists(resolvedPath)) {
               return {
                 resolvedModule: {

package/build/global-selectors.d.ts

@@ -1 +0,0 @@
-export declare function globalClassNamesIn(css: string): Set<string>;

package/build/global-selectors.js

@@ -1,22 +0,0 @@
-// A light, independent scan for `:global(...)`-wrapped selectors inside a scoped CSS block's
-// raw text. parseCSS's extractClassName already UNWRAPS :global(...) (so `:global(.reset)`
-// parses to the same `reset` key a plain `.reset` selector would), but its output has no marker
-// for "this key came from inside :global()" — parseCSS's return shape is deliberately just
-// `{ className: style }`, no per-key metadata. A caller doing its own scope-suffixing (Vue's
-// <style scoped>/<style module>, or a standalone .module.css file) needs that distinction to
-// exempt these names, so it re-derives it here with its own minimal regex, independent of the
-// full CSS-to-style pipeline. Only the single-class form (`:global(.name)`) is recognized,
-// matching extractClassName's own documented narrower gap for partial/nested :global() wrapping.
-import { kebabToCamel } from "./parser/index.js";
-const GLOBAL_SELECTOR_PATTERN = /:global\(\s*\.([a-zA-Z0-9_-]+)\s*\)/g;
-export function globalClassNamesIn(css) {
-    const names = new Set();
-    let match;
-    while ((match = GLOBAL_SELECTOR_PATTERN.exec(css)) !== null) {
-        // Normalize kebab->camel: parseCSS's output is always camelCase-keyed, but the regex above
-        // captures the CSS text verbatim — a kebab selector like `:global(.reset-btn)` would
-        // otherwise never match its own `resetBtn` key.
-        names.add(kebabToCamel(match[1]));
-    }
-    return names;
-}

package/build/parser/index.d.ts

@@ -1,22 +0,0 @@
-export type ICssParserOptions = {
-    filename?: string;
-};
-export declare function kebabToCamel(value: string): string;
-/**
- * Extract a camelCase class name from a CSS selector, or `null` if the selector has no RN
- * equivalent (pseudo-classes/-elements, bare element selectors, the universal selector — RN has
- * no element-selector concept, so those would just pollute the output).
- *
- * - `.card` → `'card'`
- * - `#header` → `'header'`
- * - `.btn.primary` → `'btnPrimary'` (compound)
- * - `.card .title` / `.card > .title` → `'cardTitle'` (descendant/child, flattened)
- * - `[data-theme]` → `'dataTheme'` (attribute)
- * - `.my-class-name` → `'myClassName'` (kebab → camel)
- */
-export declare function extractClassName(selector: string): string | null;
-/**
- * Parse a plain CSS string into a `{ className: RNStyleObject }` map. Build-time only — never
- * ship this in the app's native JS bundle; it is meant to run inside a Metro transformer.
- */
-export declare function parseCSS(css: string, options?: ICssParserOptions): Record<string, Record<string, unknown>>;

package/build/parser/index.js

@@ -1,221 +0,0 @@
-// CSS → React Native style-object compiler. `extractClassName` and the CSS-custom-property/
-// `var()` resolution machinery are framework/target-agnostic. `evaluateCalc` treats `px` as
-// identity (RN has no cell grid to scale against) and `rem`/`em` as scaled by the same
-// {@link REM_TO_PX} constant as a bare value (see values.ts). `mapCSSProperty` (properties.ts)
-// targets RN's `ViewStyle`/`TextStyle`.
-import postcss from 'postcss';
-import valueParser from 'postcss-value-parser';
-import { mapCSSProperty } from "../properties.js";
-import { REM_TO_PX } from "../values.js";
-//#region Selector utilities
-// Exported: the SFC style compiler (metro-vue-transformer.js) reuses this exact conversion to
-// normalize a template's kebab-case class="section-label" authoring to the camelCase key this
-// module already registers CSS selectors under, so both spellings resolve to the same style.
-export function kebabToCamel(value) {
-    return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-}
-function capitalize(value) {
-    return value.charAt(0).toUpperCase() + value.slice(1);
-}
-function unescapeIdentifier(value) {
-    return value.replace(/\\(.)/g, '$1');
-}
-/**
- * Extract a camelCase class name from a CSS selector, or `null` if the selector has no RN
- * equivalent (pseudo-classes/-elements, bare element selectors, the universal selector — RN has
- * no element-selector concept, so those would just pollute the output).
- *
- * - `.card` → `'card'`
- * - `#header` → `'header'`
- * - `.btn.primary` → `'btnPrimary'` (compound)
- * - `.card .title` / `.card > .title` → `'cardTitle'` (descendant/child, flattened)
- * - `[data-theme]` → `'dataTheme'` (attribute)
- * - `.my-class-name` → `'myClassName'` (kebab → camel)
- */
-export function extractClassName(selector) {
-    const trimmed = selector.trim();
-    if (/^[a-z]+$/i.test(trimmed))
-        return null;
-    if (trimmed === '*')
-        return null;
-    // `:global(...)` (Vue `<style scoped>` escape hatch) opts a selector out of scope-suffixing —
-    // a caller concern outside this package. Here it just needs unwrapping: when the WHOLE trimmed
-    // selector is one `:global(...)` wrapper, recurse on its inner text and return whatever that
-    // resolves to, reusing every selector shape below instead of duplicating it. Checked before the
-    // "starts with :" / "any colon anywhere" guards, since `:global(...)` legitimately contains a
-    // colon that must not trigger them. Known gap: a `:global(...)` wrapping only PART of a larger
-    // compound/descendant selector (e.g. `.card :global(.reset)`) is NOT unwrapped by this check.
-    const globalMatch = trimmed.match(/^:global\(\s*(.+?)\s*\)$/);
-    if (globalMatch?.[1])
-        return extractClassName(globalMatch[1]);
-    if (trimmed.startsWith(':'))
-        return null;
-    // A pseudo-class/-element trailing a class/id selector (`.card:hover`, `.card::before`) has
-    // no RN equivalent — RN has no hover/focus/nth-child style variants — so the WHOLE rule is
-    // dropped, same as a bare `:hover`. Stripping just the pseudo suffix and keeping `.card`'s
-    // other declarations would be wrong: it'd silently merge hover-only styles into the
-    // always-applied base style (a real gap an earlier version of this fix had — found by
-    // manually running the parser on `.card:hover { opacity: 0.5 }` and seeing `opacity` leak
-    // into `card`'s permanent style). `[...]` is excluded first since an attribute selector's
-    // value may legitimately contain a colon (`[data-x="a:b"]`).
-    if (trimmed.replace(/\[[^\]]*\]/g, '').includes(':'))
-        return null;
-    // Compound selector (`.btn.primary`, `div.card`) — split on unescaped dots.
-    if (trimmed.includes('.') && !trimmed.includes(' ') && !trimmed.includes('>')) {
-        const parts = trimmed.split(/(?<!\\)\./).filter(Boolean);
-        if (parts.length > 0) {
-            const startsWithElement = !trimmed.startsWith('.');
-            const startIndex = startsWithElement ? 1 : 0;
-            if (startIndex >= parts.length)
-                return null;
-            return parts
-                .slice(startIndex)
-                .map((part, i) => {
-                const camelPart = kebabToCamel(unescapeIdentifier(part));
-                return i === 0 ? camelPart : capitalize(camelPart);
-            })
-                .join('');
-        }
-    }
-    // Descendant/child selector (`.card .title`, `.card > .title`) — flattened into one name.
-    if (trimmed.includes(' ')) {
-        const parts = trimmed.split(/\s+(?:>\s*)?/).filter(Boolean);
-        const classNames = [];
-        for (const part of parts) {
-            const classMatch = part.match(/\.((?:[a-zA-Z0-9_-]|\\.)+)/);
-            if (classMatch?.[1]) {
-                classNames.push(unescapeIdentifier(classMatch[1]));
-                continue;
-            }
-            const idMatch = part.match(/#((?:[a-zA-Z0-9_-]|\\.)+)/);
-            if (idMatch?.[1])
-                classNames.push(unescapeIdentifier(idMatch[1]));
-        }
-        if (classNames.length === 0)
-            return null;
-        return classNames
-            .map((name, i) => {
-            const camelName = kebabToCamel(name);
-            return i === 0 ? camelName : capitalize(camelName);
-        })
-            .join('');
-    }
-    // Single class selector (`.card`).
-    const classMatch = trimmed.match(/^\.((?:[a-zA-Z0-9_-]|\\.)+)/);
-    if (classMatch?.[1])
-        return kebabToCamel(unescapeIdentifier(classMatch[1]));
-    // ID selector (`#header`).
-    const idMatch = trimmed.match(/^#((?:[a-zA-Z0-9_-]|\\.)+)/);
-    if (idMatch?.[1])
-        return kebabToCamel(unescapeIdentifier(idMatch[1]));
-    // Attribute selector (`[data-theme]`).
-    const attrMatch = trimmed.match(/^\[([a-zA-Z0-9_-]+)(?:=[^\]]+)?\]/);
-    if (attrMatch?.[1])
-        return kebabToCamel(attrMatch[1]);
-    return null;
-}
-//#endregion Selector utilities
-//#region var() resolution
-function resolveVariables(value, variables) {
-    if (!value.includes('var('))
-        return value;
-    const parsed = valueParser(value);
-    parsed.walk((node, index, nodes) => {
-        if (node.type !== 'function' || node.value !== 'var' || node.nodes.length === 0)
-            return;
-        const varName = node.nodes[0]?.value;
-        if (!varName)
-            return;
-        const fallbackNode = node.nodes.length > 2 ? node.nodes[2] : undefined;
-        const resolved = variables.get(varName) ?? fallbackNode?.value ?? '';
-        if (!resolved)
-            return;
-        // Replace the `var(...)` function node in its containing array with a plain word node
-        // holding the resolved text, instead of mutating `node`'s discriminated `type` in place.
-        nodes[index] = {
-            type: 'word',
-            value: resolveVariables(resolved, variables),
-            sourceIndex: node.sourceIndex,
-            sourceEndIndex: node.sourceEndIndex,
-        };
-    });
-    return parsed.toString();
-}
-//#endregion var() resolution
-//#region calc() evaluation
-const CALC_TERM_PATTERN = /calc\(([^)]+)\)/g;
-const NUMBER_WITH_UNIT_PATTERN = /(-?\d+(?:\.\d+)?)(rem|em|px)?/g;
-/**
- * Evaluates a narrow shape of `calc()`: a single multiplication, or the first numeric term
- * as a fallback. `px` is identity; `rem`/`em` scale by {@link REM_TO_PX}, matching a bare
- * dimension value.
- */
-function evaluateCalc(value) {
-    if (!value.includes('calc('))
-        return value;
-    return value.replace(CALC_TERM_PATTERN, (_, expr) => {
-        const matches = expr.match(NUMBER_WITH_UNIT_PATTERN) ?? [];
-        const values = [];
-        for (const term of matches) {
-            const numMatch = term.match(/(-?\d+(?:\.\d+)?)(rem|em|px)?/);
-            if (!numMatch)
-                continue;
-            const amount = parseFloat(numMatch[1]);
-            const unit = numMatch[2];
-            values.push(unit === 'rem' || unit === 'em' ? amount * REM_TO_PX : amount);
-        }
-        if (expr.includes('*')) {
-            const parts = expr.split('*').map(part => part.trim());
-            if (parts.length === 2) {
-                const a = values[0] ?? parseFloat(parts[0]) ?? 0;
-                const b = parseFloat(parts[1]) || 1;
-                return String(Math.round(a * b));
-            }
-        }
-        return String(Math.round(values[0] ?? 0));
-    });
-}
-//#endregion calc() evaluation
-/**
- * Parse a plain CSS string into a `{ className: RNStyleObject }` map. Build-time only — never
- * ship this in the app's native JS bundle; it is meant to run inside a Metro transformer.
- */
-export function parseCSS(css, options) {
-    if (!css || typeof css !== 'string')
-        return {};
-    const root = postcss.parse(css, { from: options?.filename });
-    const styles = {};
-    const warnedProperties = new Set();
-    // `@media` (and any other at-rule) is unsupported; drop it before the rule walk below so its
-    // nested rules never leak into the output.
-    root.walkAtRules(atRule => {
-        console.warn(`[@symbiote-native/css-parser] "@${atRule.name}" at-rules are not supported, "@${atRule.name} ${atRule.params}" skipped`);
-        atRule.remove();
-    });
-    const variables = new Map();
-    root.walkDecls(decl => {
-        if (decl.prop.startsWith('--'))
-            variables.set(decl.prop, decl.value);
-    });
-    root.walkRules(rule => {
-        const selectors = rule.selector.split(',').map(selector => selector.trim());
-        for (const selector of selectors) {
-            const className = extractClassName(selector);
-            if (!className)
-                continue;
-            const style = {};
-            rule.walkDecls(decl => {
-                if (decl.prop.startsWith('--'))
-                    return;
-                const resolvedValue = evaluateCalc(resolveVariables(decl.value, variables));
-                const mapped = mapCSSProperty(decl.prop.toLowerCase(), resolvedValue, warnedProperties);
-                if (mapped)
-                    Object.assign(style, mapped);
-            });
-            if (Object.keys(style).length === 0)
-                continue;
-            styles[className] = { ...styles[className], ...style };
-        }
-    });
-    return styles;
-}