@symbiote-native/css-parser 0.2.3 → 0.4.0

package/README.md

@@ -32,32 +32,35 @@ Node build machine — never shipped in the app's native JS bundle. Each adapter
 as a regular dependency and re-exports it via its own `./metro-css-parser` subpath, so a consuming
 app's `metro.config.js` wires:
 
-```js
-// metro-css-transformer.js, in the app
-const { createCssMetroTransformer } = require('@symbiote-native/react/metro-css-parser');
-module.exports = createCssMetroTransformer(require('@react-native/metro-babel-transformer'));
-```
-
 ```js
 // metro.config.js
 resolver: { sourceExts: [...defaultSourceExts, 'css', 'scss', 'sass', 'less', 'styl'] },
-transformer: { babelTransformerPath: require.resolve('./metro-css-transformer.js') },
+transformer: { babelTransformerPath: require.resolve('@symbiote-native/react/metro-css-parser') },
 ```
 
+The subpath already calls `createCssMetroTransformer` and exports the finished transformer, so an
+app writes no transformer file of its own — point `babelTransformerPath` straight at it. Reach for
+`createCssMetroTransformer` only when building the subpath for a NEW adapter.
+
 From there, a plain stylesheet import just works, from any adapter's own source file:
 
 ```ts
-import styles from './Card.module.css';   // CSS Modules — default export is a name→scopedName map
-import './theme.css';                     // plain CSS — registers classes globally, no export
+import styles from './Card.module.css'; // CSS Modules — default export is a name→scopedName map
+import './theme.css'; // plain CSS — registers classes globally, no export
 ```
 
 ```tsx
-<View className="card" style={styles.highlight} />   // React
+<View className="card" style={styles.highlight} /> // React
 ```
+
 ```html
 <!-- Vue SFC -->
 <view :class="['card', { active: isActive }]" />
-<style scoped>.card { padding: 10px; }</style>
+<style scoped>
+  .card {
+    padding: 10px;
+  }
+</style>
 ```
 
 ## The pipeline
@@ -67,31 +70,48 @@ import './theme.css';                     // plain CSS — registers classes glo
       │  (build time, Metro)                                       │  (runtime, all adapters)
       ▼                                                             ▼
 @symbiote-native/css-parser                              @symbiote-native/engine's style-registry
-  preprocessors.ts → parser.ts (parseCSS)            registerStyles() / resolveClassName()
+  preprocessors → lightning (compileCssToRules)       registerRules() / resolveClassName()
 ```
 
 A preprocessor source is reduced to plain CSS text first (`compileScss`/`compileSass`/
-`compileLess`/`compileStylus`); `parseCSS()` is the single downstream consumer either way, so every
-mechanism below runs identically regardless of source language.
+`compileLess`/`compileStylus`); `compileCssToRules()` is the single downstream consumer either way,
+so every mechanism below runs identically regardless of source language.
 
 ## API surface
 
 ```ts
 import {
-  parseCSS, extractClassName, kebabToCamel,       // core compiler
-  compileCssFile, isCssModuleFile,                 // standalone .css/.module.css files
-  createCssMetroTransformer,                       // Metro babelTransformerPath factory
-  compileScss, compileSass, compileLess, compileStylus, compile, detectLanguage, isStyleFile,
-  classNamesToDtsSource, generateModuleDts,        // .d.ts generation for CSS Modules typing
-  globalClassNamesIn, hashFilePath,
+  compileCssToRules, // core compiler
+  compileScopedCss, // a scoped <style> block, rules + name map
+  compileCssFile,
+  isCssModuleFile, // standalone .css/.module.css files
+  createCssMetroTransformer, // Metro babelTransformerPath factory
+  compileScss,
+  compileSass,
+  compileLess,
+  compileStylus,
+  compile,
+  detectLanguage,
+  isStyleFile,
+  classNamesToDtsSource,
+  generateModuleDts, // .d.ts generation for CSS Modules typing
+  hashFilePath,
 } from '@symbiote-native/css-parser';
 ```
 
-- **`parseCSS(css, { filename? })`** — the compiler core: postcss AST walk, `var()`/`calc()`
-  resolution, selector → camelCase key (`.card` → `card`, `.btn.primary` → `btnPrimary` compound,
-  `.card .title` → `cardTitle` descendant). A selector containing a pseudo-class (`:hover`, …) is
-  dropped whole — RN has no pseudo-class concept, so there is no partial-application semantics to
-  preserve.
+- **`compileCssToRules(css, { filename, pattern?, remToPx? })`** — the compiler core: one
+  lightningcss pass over the typed AST, resolving `var()`/`calc()` and emitting a `rules` array.
+  Each rule carries the class TOKENS its selector was written with — as authored, never camelCased
+  or collapsed into a single key — plus specificity and source order, so the registry matches by
+  token subset instead of reversing a guess. With a CSS-Modules `pattern` it also returns the
+  authored→renamed `exports` map and `globals`, the tokens lightningcss did NOT rename, which is
+  exactly the set the author put inside `:global(...)`. A selector containing a pseudo-class
+  (`:hover`, …) is dropped whole — RN has no pseudo-class concept, so there is no
+  partial-application semantics to preserve.
+- **`compileScopedCss(css, { filename, pattern })`** — the scoped-block form (a Svelte `<style>`, a
+  Vue `<style scoped>`): the same rules plus the authored→scoped name map its markup rewriter
+  resolves every class token through. Both halves come out of ONE compile, so the style side and
+  the markup side cannot disagree on a name.
 - **`compileCssFile` / `isCssModuleFile`** — the standalone-file form: `Card.module.css`'s classes
   are always scoped to a per-file hash and its default export is the name→scopedName map; a plain
   `.css` file registers globally via a side-effect import.
@@ -121,7 +141,7 @@ import {
 
 ## Related packages
 
-- [`@symbiote-native/engine`](../engine) — owns the runtime `style-registry` (`registerStyles` /
+- [`@symbiote-native/engine`](../engine) — owns the runtime `style-registry` (`registerRules` /
   `resolveClassName`) this package's compiled output resolves against, and the class+style merge
   used by every adapter.
 - [`@symbiote-native/react`](../../adapters/react) / [`@symbiote-native/vue`](../../adapters/vue) /

package/build/generate-dts/index.js

@@ -8,9 +8,7 @@
 // appended rather than replaced — e.g. `Card.module.css.d.ts`) so TypeScript's own module
 // resolution picks it up for a default import of `Card.module.css` without a separate
 // registration step, the same convention typed-css-modules uses.
-import { parseCSS } from "../parser/index.js";
-import { compile, detectLanguage } from "../preprocessors/index.js";
-import { isCssModuleFile } from "../metro-css-module/index.js";
+import { isCssModuleFile, moduleClassNames, } from "../metro-css-module/index.js";
 const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 function formatKey(className) {
     return IDENTIFIER_RE.test(className) ? className : JSON.stringify(className);
@@ -31,13 +29,10 @@ export function classNamesToDtsSource(classNames) {
     ].join('\n');
 }
 // Mirrors compileCssFile's own module/non-module branch: a plain (non-`.module.*`) style file
-// has no default export to type (registerStyles() runs as a side effect only), so it gets no
+// has no default export to type (registerRules() runs as a side effect only), so it gets no
 // `.d.ts` at all.
 export async function generateModuleDts(source, filename) {
     if (!isCssModuleFile(filename))
         return null;
-    const lang = detectLanguage(filename);
-    const css = lang === 'css' ? source : await compile(source, lang, filename);
-    const parsed = parseCSS(css, { filename });
-    return classNamesToDtsSource(Object.keys(parsed));
+    return classNamesToDtsSource(await moduleClassNames(source, filename));
 }

package/build/generate-dts-cli.js

@@ -17,7 +17,11 @@ import * as path from 'node:path';
 import { isStyleFile } from "./preprocessors/index.js";
 import { isCssModuleFile } from "./metro-css-module/index.js";
 import { generateModuleDts } from "./generate-dts/index.js";
-const SKIPPED_DIR_NAMES = new Set(['node_modules', 'build', '.git']);
+const SKIPPED_DIR_NAMES = new Set([
+    'node_modules',
+    'build',
+    '.git',
+]);
 async function collectModuleStyleFiles(root) {
     const stat = await fs.stat(root);
     if (!stat.isDirectory()) {

package/build/golden-corpus/fixtures/ScopedGlobalDemo.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+  // Fixture, not a running component. examples/svelte has exactly one styled component and it
+  // carries no :global(), so the escape hatch had no golden coverage on this adapter either.
+  let isLoud = $state(false);
+</script>
+
+<View class="panel">
+  <View class="panel wide" />
+  <View class={['panel', isLoud && 'wide']} />
+  <View class="untouched" />
+</View>
+
+<style>
+  .panel {
+    padding: 9px;
+  }
+
+  .panel.wide {
+    padding: 19px;
+  }
+
+  :global(.untouched) {
+    margin: 0;
+  }
+</style>

package/build/golden-corpus/fixtures/ScopedGlobalDemo.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const ScopedGlobalDemo: import("svelte").Component<Record<string, never>, {}, "">;
+type ScopedGlobalDemo = ReturnType<typeof ScopedGlobalDemo>;
+export default ScopedGlobalDemo;

package/build/index.d.ts

@@ -1,11 +1,12 @@
-export { parseCSS, extractClassName, kebabToCamel } from './parser/index.ts';
-export type { ICssParserOptions } from './parser/index.ts';
-export { globalClassNamesIn } from './global-selectors.ts';
+export { compileCssToRules } from './lightning/rules.ts';
+export type { ICompiledCss, ICompileRulesOptions, IStyleRule, } from './lightning/rules.ts';
 export { hashFilePath } from './file-scope-id.ts';
-export { compileCssFile, isCssModuleFile } from './metro-css-module/index.ts';
-export type { ICompiledCssFile } from './metro-css-module/index.ts';
-export { classNamesToDtsSource, generateModuleDts } from './generate-dts/index.ts';
+export { compileScopedCss } from './scoped-classes.ts';
+export type { IScopedCss, IScopedCssOptions } from './scoped-classes.ts';
+export { compileCssFile, compileCssModule, isCssModuleFile, } from './metro-css-module/index.ts';
+export type { ICompiledCssFile, ICompiledCssModule, } from './metro-css-module/index.ts';
+export { classNamesToDtsSource, generateModuleDts, } from './generate-dts/index.ts';
 export { createCssMetroTransformer, resolveUpstreamTransformer, } from './metro-transformer/index.ts';
-export type { IMetroTransformer, IMetroTransformParams } from './metro-transformer/index.ts';
+export type { IMetroTransformer, IMetroTransformParams, } from './metro-transformer/index.ts';
 export { compileScss, compileSass, compileLess, compileStylus, compile, detectLanguage, isStyleFile, } from './preprocessors/index.ts';
 export type { IPreprocessorLanguage } from './preprocessors/index.ts';

package/build/index.js

@@ -1,7 +1,7 @@
-export { parseCSS, extractClassName, kebabToCamel } from "./parser/index.js";
-export { globalClassNamesIn } from "./global-selectors.js";
+export { compileCssToRules } from "./lightning/rules.js";
 export { hashFilePath } from "./file-scope-id.js";
-export { compileCssFile, isCssModuleFile } from "./metro-css-module/index.js";
-export { classNamesToDtsSource, generateModuleDts } from "./generate-dts/index.js";
+export { compileScopedCss } from "./scoped-classes.js";
+export { compileCssFile, compileCssModule, isCssModuleFile, } from "./metro-css-module/index.js";
+export { classNamesToDtsSource, generateModuleDts, } from "./generate-dts/index.js";
 export { createCssMetroTransformer, resolveUpstreamTransformer, } from "./metro-transformer/index.js";
 export { compileScss, compileSass, compileLess, compileStylus, compile, detectLanguage, isStyleFile, } from "./preprocessors/index.js";

package/build/lightning/declarations.d.ts

@@ -0,0 +1,46 @@
+/**
+ * An OBJECT-shaped RN style value. `core/engine/src/styles.ts` has exactly one such field,
+ * `shadowOffset?: { width: number; height: number }`; RN's `textShadowOffset` has the same shape
+ * (it is missing from `ITextStyle` there, but `textShadowToStyle` below emits it and RN reads
+ * it). Both are all-number, so one record type covers the family.
+ */
+export type IStyleValueObject = Readonly<Record<string, number>>;
+/**
+ * One React Native style value.
+ *
+ * Most are scalars. Two are objects ({@link IStyleValueObject}). Six are ARRAY-capable in RN —
+ * `transform: ITransformProp[]`, `boxShadow`, `filter`, `experimental_backgroundImage`,
+ * `transformOrigin`, `fontVariant` — but every one of them is `raw` in PROPERTY_TABLE, i.e. this
+ * pipeline hands the engine the CSS TEXT and lets its own processors (`process-transform`,
+ * `process-box-shadow`, …) build the array at commit time. So the array branch exists so the
+ * integration step cannot hit a second widening, not because a declaration produces one today.
+ */
+export type IStyleValue = string | number | IStyleValueObject | ReadonlyArray<string | number | IStyleValueObject>;
+export type IStyleObject = Record<string, IStyleValue>;
+export interface IDeclarationContext {
+    readonly filename: string;
+    /** Custom properties (`--x`) collected from the whole file, name -> raw value text. */
+    readonly variables: ReadonlyMap<string, string>;
+    /** Root font size for rem, default 16. */
+    readonly remToPx?: number;
+}
+/**
+ * One lightningcss `Declaration` (the object handed to a visitor / found in
+ * `rule.value.declarations.declarations`) mapped to zero or more RN style entries.
+ */
+export declare function declarationToStyle(declaration: unknown, context: IDeclarationContext): IStyleObject;
+/**
+ * Every custom property (`--x`) declared anywhere in the file, name -> its raw value text, in the
+ * shape {@link IDeclarationContext.variables} expects.
+ *
+ * A pass of its OWN, ahead of mapping declarations, because nothing orders `:root` first — a
+ * component stylesheet may declare a token in a class rule, inside `@media`, or below its first
+ * use, and a single forward walk would miss it. Later declaration of the same name wins, which is
+ * what the cascade does within one file.
+ *
+ * The value is stored VERBATIM: a token list that is itself a `var()` chain is printed back as
+ * `var(--other)`, and resolution stays in {@link declarationToStyle}, which is the only place that
+ * knows whether the chain terminates. Serialization goes through the same token printer the
+ * `unparsed` path uses — this package keeps ONE printer.
+ */
+export declare function variablesIn(css: string, filename: string): ReadonlyMap<string, string>;