@symbiote-native/css-parser 0.1.1 → 0.2.1

package/README.md

@@ -14,6 +14,16 @@ 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:
+
+```bash
+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

package/build/generate-dts.js

@@ -1,6 +1,6 @@
 // Generates a real on-disk `.d.ts` for a `.module.css` (or `.module.scss`/`.module.less`/
-// `.module.styl`) file — the follow-up the symbiote-sfc-style-compiler skill records as
-// deliberately deferred when CSS Modules shipped. Unlike Volar's built-in `<style module>`
+// `.module.styl`) file, giving CSS Modules imports real compile-time type checking.
+// Unlike Volar's built-in `<style module>`
 // typing for inline Vue SFC blocks (which synthesizes `Record<string, string> & {known keys}` —
 // an index signature that still accepts any key, so it never catches a typo), the type emitted
 // here has NO index signature: a typo in `styles.typo` is a genuine `error TS2339` under `tsc`/

package/build/index.d.ts

@@ -5,7 +5,7 @@ export { hashFilePath } from './file-scope-id.ts';
 export { compileCssFile, isCssModuleFile } from './metro-css-module.ts';
 export type { ICompiledCssFile } from './metro-css-module.ts';
 export { classNamesToDtsSource, generateModuleDts } from './generate-dts.ts';
-export { createCssMetroTransformer } from './metro-transformer.ts';
+export { createCssMetroTransformer, resolveUpstreamTransformer } from './metro-transformer.ts';
 export type { IMetroTransformer, IMetroTransformParams } from './metro-transformer.ts';
 export { compileScss, compileSass, compileLess, compileStylus, compile, detectLanguage, isStyleFile, } from './preprocessors.ts';
 export type { IPreprocessorLanguage } from './preprocessors.ts';

package/build/index.js

@@ -3,5 +3,5 @@ export { globalClassNamesIn } from "./global-selectors.js";
 export { hashFilePath } from "./file-scope-id.js";
 export { compileCssFile, isCssModuleFile } from "./metro-css-module.js";
 export { classNamesToDtsSource, generateModuleDts } from "./generate-dts.js";
-export { createCssMetroTransformer } from "./metro-transformer.js";
+export { createCssMetroTransformer, resolveUpstreamTransformer } from "./metro-transformer.js";
 export { compileScss, compileSass, compileLess, compileStylus, compile, detectLanguage, isStyleFile, } from "./preprocessors.js";

package/build/metro-css-module.js

@@ -2,7 +2,7 @@
 // plain JS module — the framework-agnostic twin of a Vue SFC's inline <style>/<style module>
 // block (examples/vue-sfc/metro-vue-transformer.js), usable from ANY adapter's own source file:
 // `import styles from './Card.module.scss'` works the same from a React .tsx, a Vue <script>, or
-// an Angular .ts. See the symbiote-sfc-style-compiler skill.
+// an Angular .ts.
 //
 // A plain style file registers its classes globally, exactly like an unscoped Vue <style>
 // block — side-effect import only (`import './theme.scss'`), no default export. A `.module.*`

package/build/metro-transformer.d.ts

@@ -7,4 +7,5 @@ export interface IMetroTransformer {
     transform: (params: IMetroTransformParams) => unknown;
     getCacheKey?: (...args: unknown[]) => string;
 }
-export declare function createCssMetroTransformer(upstreamTransformer: IMetroTransformer): IMetroTransformer;
+export declare function resolveUpstreamTransformer(): IMetroTransformer;
+export declare function createCssMetroTransformer(upstreamTransformer?: IMetroTransformer): IMetroTransformer;

package/build/metro-transformer.js

@@ -1,12 +1,12 @@
 // A ready-made Metro babel transformer wrapper for .css/.scss/.sass/.less/.styl (+ their
-// .module.* twins) support, so a consuming app's own metro.config.js needs only a 3-line wiring
-// file instead of hand-rolling the "compile a style file, delegate everything else to upstream"
-// boilerplate three times (once per adapter's example, before this existed). @symbiote-native/css-parser
-// is a regular `dependency` of every adapter package (@symbiote-native/react, @symbiote-native/vue,
-// @symbiote-native/angular), so this is transitively resolvable from any app that already depends on one
-// of them — this repo's shamefully-hoist pnpm config (.npmrc) makes that resolvable without the
-// app adding @symbiote-native/css-parser to its own package.json. See the symbiote-sfc-style-compiler
-// skill.
+// .module.* twins) support, so a consuming app's own metro.config.js needs only
+// `babelTransformerPath: require.resolve('@symbiote-native/<adapter>/metro-css-parser')` instead of
+// hand-rolling the "compile a style file, delegate everything else to upstream" boilerplate once
+// per adapter's example. @symbiote-native/css-parser is a regular `dependency` of every adapter
+// package (@symbiote-native/react, @symbiote-native/vue, @symbiote-native/angular), so this is
+// transitively resolvable from any app that already depends on one of them — this repo's
+// shamefully-hoist pnpm config (.npmrc) makes that resolvable without the app adding
+// @symbiote-native/css-parser to its own package.json.
 //
 // Sync vs async: `transform()` is async uniformly, for every recognized style extension
 // including plain `.css`. Metro's own `metro-transform-worker` already does
@@ -22,9 +22,22 @@
 // duplication. `return upstreamTransformer.transform(...)` as the last line of an async function
 // forwards whatever it returns (Promise or not) as this function's own resolved value with no
 // extra `await` needed; Metro awaits the whole chain regardless.
+import { createRequire } from 'node:module';
 import { compileCssFile } from "./metro-css-module.js";
 import { isStyleFile } from "./preprocessors.js";
-export function createCssMetroTransformer(upstreamTransformer) {
+// @react-native/metro-babel-transformer is a real `dependency` of this package (not merely a
+// peer/dev dep), so it lands in css-parser's OWN resolvable node_modules under pnpm — no
+// hoisting or `paths`-anchored require.resolve trick needed, unlike the app-local workaround
+// this replaces (formerly duplicated in every adapter's example metro-css-transformer.js).
+// Exported (not just used internally) so a per-framework Metro transformer that ALSO needs to
+// delegate to the upstream RN transformer (the Vue SFC transformer, for its non-.vue passthrough
+// branch) can reuse this instead of its own fragile direct `require('@react-native/metro-babel-
+// transformer')`, which would only resolve for an external install by accident of hoisting.
+export function resolveUpstreamTransformer() {
+    const require = createRequire(import.meta.url);
+    return require('@react-native/metro-babel-transformer');
+}
+export function createCssMetroTransformer(upstreamTransformer = resolveUpstreamTransformer()) {
     return {
         async transform(params) {
             if (!isStyleFile(params.filename))

package/build/parser.js

@@ -1,10 +1,8 @@
-// CSS → React Native style-object compiler. Ported from wolf-tui's
-// `internal/css-parser/src/parser.ts`: `extractClassName` and the CSS-custom-property/`var()`
-// resolution machinery are framework/target-agnostic and carry over near-verbatim. `evaluateCalc`
-// drops wolf-tui's terminal-cell scaling (`1rem = 4 cells`, `4px = 1 cell`) — RN has no cell grid,
-// so `px` is identity and `rem`/`em` use the same {@link REM_TO_PX} constant as a bare value
-// (see values.ts). `mapCSSProperty` (properties.ts) targets RN's `ViewStyle`/`TextStyle` instead
-// of wolfie's `Styles`.
+// 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";
@@ -148,9 +146,9 @@ function resolveVariables(value, variables) {
 const CALC_TERM_PATTERN = /calc\(([^)]+)\)/g;
 const NUMBER_WITH_UNIT_PATTERN = /(-?\d+(?:\.\d+)?)(rem|em|px)?/g;
 /**
- * Evaluates the narrow shape of `calc()` wolf-tui supported (a single multiplication, or the
- * first numeric term as a fallback) — ported verbatim minus the terminal-cell unit scale.
- * `px` is identity; `rem`/`em` scale by {@link REM_TO_PX}, matching a bare dimension value.
+ * 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('))

package/build/preprocessors.js

@@ -1,9 +1,7 @@
 // Optional SCSS/Sass, Less, and Stylus preprocessor support. Each compiler here only ever reduces
 // its own syntax down to plain CSS text — parser.ts's `parseCSS()` is the single, UNCHANGED
-// downstream consumer of that text, exactly as it always was for a plain `.css` file. Ported from
-// wolf-tui's `internal/css-parser/src/preprocessors.ts` (the SCSS/Less/Stylus shape only — that
-// file's Tailwind branch is a separate, out-of-scope concern here, see the
-// symbiote-sfc-style-compiler skill).
+// downstream consumer of that text, exactly as it always was for a plain `.css` file. Tailwind
+// is a separate, out-of-scope concern and has no branch here.
 //
 // `sass`/`less`/`stylus` are lazy `import()`ed, never a top-level import, and are
 // devDependencies of THIS package ONLY (never a `dependency`, see package.json) — a project that

package/build/properties.js

@@ -1,8 +1,6 @@
-// CSS property → React Native ViewStyle/TextStyle prop mapping. Unlike wolf-tui's
-// `properties.ts` (which maps onto a terminal-cell `Styles` type with TUI-only concepts like
-// `borderStyle: 'round'`), RN's own style props already mirror CSS's shorthand model 1:1
-// (`margin`, `borderRadius`, `borderTopLeftRadius`, …), so this table is a flat kebab→camel
-// rename plus a value-conversion kind — no shorthand expansion is needed.
+// CSS property → React Native ViewStyle/TextStyle prop mapping. RN's own style props already
+// mirror CSS's shorthand model 1:1 (`margin`, `borderRadius`, `borderTopLeftRadius`, …), so this
+// table is a flat kebab→camel rename plus a value-conversion kind — no shorthand expansion is needed.
 import { parseNumeric, parseNumericOrPercent, parseRawValue, parseTextShadow, warnOnce, } from "./values.js";
 /**
  * kebab-case CSS property → { RN camelCase prop, value-conversion kind }.

package/build/values.js

@@ -1,6 +1,5 @@
 // CSS → React Native value conversion. RN style props take plain numbers for `px` / unitless
-// values (there is no terminal-cell or DP grid to scale onto, unlike wolf-tui's TUI target), so
-// unlike wolf-tui's `values.ts` there is no unit-to-cell division here — `px` is identity.
+// values, so there is no unit conversion needed here beyond scaling `rem`/`em` — `px` is identity.
 import valueParser from 'postcss-value-parser';
 // symbiote has no root-font-size registry (a DOM `<html>` element would own one); we pick CSS's
 // own default of a 16px root font size as the `rem` multiplier, so `2rem` reads as `32`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/css-parser",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Build-time CSS/SCSS/Less/Stylus compiler for SymbioteNative — compiles stylesheets to React Native style objects, resolved at runtime via a cross-adapter class-name registry.",
   "repository": {
     "type": "git",
@@ -39,6 +39,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@react-native/metro-babel-transformer": "0.86.0",
     "postcss": "^8.4.49",
     "postcss-value-parser": "^4.2.0"
   },

package/typescript-plugin.cjs

@@ -7,18 +7,13 @@
 // live-editing case; generate-dts-cli.ts (`css-dts`, wired to `pretypecheck`) remains the
 // separate, on-disk source of truth for `tsc`/`vue-tsc` CLI runs — plugins never load there.
 //
-// Ported from wolf-tui's `@wolf-tui/typescript-plugin` (wolf-tui/packages/typescript-plugin/
-// src/index.ts) — same core mechanism (override getScriptSnapshot + resolveModuleNameLiterals to
-// synthesize a virtual .d.ts for the import), fixing two real bugs found by reading that source
-// directly: (1) its class extractor never converts kebab-case to camelCase, so a suggested key
-// like `section-tight` does NOT match 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) its dts cache never
-// invalidates, so autocomplete goes stale after editing the CSS file until the IDE restarts
-// tsserver — this version keys the cache on the file's mtime instead. wolf-tui's package.json
-// also lists a real dependency on `@wolf-tui/css-parser` that its index.ts never actually
-// imports — a leftover of an abandoned attempt to reuse it directly, for the same reason
-// explained below.
+// 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
+// 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.
 //
 // SCOPE: plain `.module.css` only, not `.module.scss`/`.module.less`/`.module.styl` —
 // getScriptSnapshot must be fully SYNCHRONOUS (tsserver's plugin protocol has no async hook), and
@@ -31,14 +26,13 @@
 // 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. Same accepted limitation
-// wolf-tui's own README documents for its regex approach ("complex selectors may not be
-// detected").
+// 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.
 //
 // Hand-written plain CommonJS, NOT compiled from a `.ts`/`.cts` source — same convention already
-// used for each adapter's metro-css-parser.cjs shim (see the symbiote-sfc-style-compiler skill's
-// "Distribution" section). 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
+// 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