@symbiote-native/css-parser 0.3.0 → 0.5.0

package/README.md

@@ -16,9 +16,10 @@ CSS Modules all work identically regardless of source language.
 
 ## Install
 
-Not installed directly by an app — each adapter package (`@symbiote-native/react`,
-`@symbiote-native/vue`, `@symbiote-native/angular`) already depends on it and re-exports it via its
-own `./metro-css-parser` subpath. Writing a Metro transformer for a new adapter yourself:
+Not installed directly by an app — every adapter package (`@symbiote-native/react`,
+`@symbiote-native/vue`, `@symbiote-native/svelte`, `@symbiote-native/solid`,
+`@symbiote-native/angular`) already depends on it and re-exports it via its own
+`./metro-css-parser` subpath. Writing a Metro transformer for a new adapter yourself:
 
 ```bash
 npm install @symbiote-native/css-parser
@@ -27,10 +28,11 @@ npm install @symbiote-native/css-parser
 ## Who calls this, and how
 
 **An app never imports this package directly.** It runs only inside a Metro transformer, on the
-Node build machine — never shipped in the app's native JS bundle. Each adapter package
-(`@symbiote-native/react`, `@symbiote-native/vue`, `@symbiote-native/angular`) depends on `@symbiote-native/css-parser`
-as a regular dependency and re-exports it via its own `./metro-css-parser` subpath, so a consuming
-app's `metro.config.js` wires:
+Node build machine — never shipped in the app's native JS bundle. Every adapter package
+(`@symbiote-native/react`, `@symbiote-native/vue`, `@symbiote-native/svelte`,
+`@symbiote-native/solid`, `@symbiote-native/angular`) depends on `@symbiote-native/css-parser` 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.config.js
@@ -70,20 +72,19 @@ import './theme.css'; // plain CSS — registers classes globally, no export
       │  (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
+  compileCssToRules, // core compiler
+  compileScopedCss, // a scoped <style> block, rules + name map
   compileCssFile,
   isCssModuleFile, // standalone .css/.module.css files
   createCssMetroTransformer, // Metro babelTransformerPath factory
@@ -96,29 +97,28 @@ import {
   isStyleFile,
   classNamesToDtsSource,
   generateModuleDts, // .d.ts generation for CSS Modules typing
-  globalClassNamesIn,
-  globalClassTokensIn,
   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.
 - **`createCssMetroTransformer`** — wraps an upstream RN Babel transformer, detecting a stylesheet
   extension and compiling it before delegating everything else unchanged.
-- **`globalClassNamesIn` / `globalClassTokensIn`** — the two halves of `:global()`, and they answer
-  different questions. The first returns registered KEYS whose selector was global in full, so the
-  key itself skips scoping. The second returns MARKUP TOKENS that came out of a `:global(...)`
-  payload wherever it sat, including inside an otherwise-scoped selector — `.card :global(.reset)`
-  yields the key `cardReset` from neither, and the token `reset` from the second. A caller that
-  suffixes class names needs both: exempting only by key leaves a partial global's token
-  scope-mangled, exempting only by token leaves a fully global compound's rule dead.
 - **Preprocessors** — `sass`/`less`/`stylus` are lazy, **optional** `devDependencies`: a project
   that never authors `.scss`/`.less`/`.styl` never installs any of the three.
 - **CSS Modules type safety** — `css-dts` (bin) walks a directory and writes a real `<file>.d.ts`
@@ -135,18 +135,20 @@ import {
 - It does not implement Tailwind CSS — that needs whole-project class scanning and JIT utility
   generation, a fundamentally different shape than "one source file reduces to CSS text", and is
   being designed as a separate, future package.
-- It supports `scoped` / `:global()` / CSS Modules and SCSS/Sass/Less/Stylus preprocessing; it does
+- It supports `scoped` / `:global()` / CSS Modules and SCSS/Sass/Less/Stylus preprocessing —
+  including Svelte's own `<style>` block (its preprocessor calls this package's
+  `compileScopedCss`, the same compile every Vue `<style scoped>` block goes through) — and it does
   not yet generate a typed `.d.ts` for an **inline** Vue `<style module>` block (only standalone
   `.module.css` files get the strict, no-index-signature type — Vue's own Volar plugin gives inline
-  blocks a looser, typo-tolerant type for free) and has no Svelte support yet (no Svelte adapter
-  exists in SymbioteNative today).
+  blocks a looser, typo-tolerant type for free).
 
 ## 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) /
+  [`@symbiote-native/svelte`](../../adapters/svelte) / [`@symbiote-native/solid`](../../adapters/solid) /
   [`@symbiote-native/angular`](../../adapters/angular) — each depends on this package directly and
   re-exports it via its own `./metro-css-parser` subpath, so a consuming app needs no extra install
   step.

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, extractClassTokens, classTokensIn, kebabToCamel, } from './parser/index.ts';
-export type { ICssParserOptions } from './parser/index.ts';
-export { globalClassNamesIn, globalClassTokensIn } 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, extractClassTokens, classTokensIn, kebabToCamel, } from "./parser/index.js";
-export { globalClassNamesIn, globalClassTokensIn } 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>;