@symbiote-native/css-parser 0.1.0

package/build/parser.js

@@ -0,0 +1,223 @@
+// 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`.
+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 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.
+ */
+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;
+}

package/build/preprocessors.d.ts

@@ -0,0 +1,20 @@
+export type IPreprocessorLanguage = 'css' | 'scss' | 'less' | 'stylus';
+export declare function isStyleFile(filename: string): boolean;
+/** Extension → preprocessor language. `.scss`/`.sass` both route through the SCSS/Sass compiler
+ * (`compileScss` itself picks the concrete syntax off the extension); anything unrecognized is
+ * treated as plain CSS, same as today. */
+export declare function detectLanguage(filename: string): IPreprocessorLanguage;
+/** Compiles SCSS, or the indented Sass syntax when `filePath` ends in `.sass`, down to plain CSS
+ * text. `loadPaths` points at the source file's own directory so a relative `@use`/`@import`
+ * resolves the way an author would expect. */
+export declare function compileScss(source: string, filePath?: string): Promise<string>;
+export declare const compileSass: typeof compileScss;
+/** Compiles Less down to plain CSS text. Less has no synchronous render API. */
+export declare function compileLess(source: string, filePath?: string): Promise<string>;
+/** Compiles Stylus down to plain CSS text. Stylus's `render` is callback-based; wrapped in a
+ * Promise so it composes with the rest of this module's async API. */
+export declare function compileStylus(source: string, filePath?: string): Promise<string>;
+/** Unified entry point: reduces any recognized preprocessor language down to plain CSS text.
+ * `lang: 'css'` is a no-op passthrough — callers decide whether preprocessing is needed at all,
+ * typically via {@link detectLanguage}. */
+export declare function compile(source: string, lang: IPreprocessorLanguage, filePath?: string): Promise<string>;

package/build/preprocessors.js

@@ -0,0 +1,128 @@
+// 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).
+//
+// `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
+// never authors `.scss`/`.less`/`.styl` must never be forced to install any of the three. The
+// loaders below throw an install-instruction error the first time a preprocessor is actually
+// needed and its package turns out to be missing, instead of failing this package's whole module
+// graph at import time.
+import * as path from 'node:path';
+// Every extension this module recognizes as "a style file, possibly needing preprocessing" —
+// the one list `isStyleFile` (the Metro-transformer-facing "should I even look at this file?"
+// check) and `detectLanguage` (the "which compiler?" check) both key off, so a new preprocessor
+// extension is added in exactly one place.
+const RECOGNIZED_EXTENSIONS = new Map([
+    ['.css', 'css'],
+    ['.scss', 'scss'],
+    ['.sass', 'scss'],
+    ['.less', 'less'],
+    ['.styl', 'stylus'],
+    ['.stylus', 'stylus'],
+]);
+export function isStyleFile(filename) {
+    return RECOGNIZED_EXTENSIONS.has(path.extname(filename).toLowerCase());
+}
+/** Extension → preprocessor language. `.scss`/`.sass` both route through the SCSS/Sass compiler
+ * (`compileScss` itself picks the concrete syntax off the extension); anything unrecognized is
+ * treated as plain CSS, same as today. */
+export function detectLanguage(filename) {
+    return RECOGNIZED_EXTENSIONS.get(path.extname(filename).toLowerCase()) ?? 'css';
+}
+let sassModule;
+let lessModule;
+let stylusModule;
+async function loadSass() {
+    if (!sassModule) {
+        try {
+            sassModule = await import('sass');
+        }
+        catch {
+            throw new Error('sass is required for .scss/.sass files. Install it: npm i -D sass');
+        }
+    }
+    return sassModule;
+}
+async function loadLess() {
+    if (!lessModule) {
+        try {
+            const mod = await import('less');
+            lessModule = mod.default ?? mod;
+        }
+        catch {
+            throw new Error('less is required for .less files. Install it: npm i -D less');
+        }
+    }
+    return lessModule;
+}
+async function loadStylus() {
+    if (!stylusModule) {
+        try {
+            const mod = await import('stylus');
+            stylusModule = mod.default ?? mod;
+        }
+        catch {
+            throw new Error('stylus is required for .styl files. Install it: npm i -D stylus');
+        }
+    }
+    return stylusModule;
+}
+/** Compiles SCSS, or the indented Sass syntax when `filePath` ends in `.sass`, down to plain CSS
+ * text. `loadPaths` points at the source file's own directory so a relative `@use`/`@import`
+ * resolves the way an author would expect. */
+export async function compileScss(source, filePath) {
+    const sass = await loadSass();
+    const result = sass.compileString(source, {
+        loadPaths: filePath ? [path.dirname(filePath)] : [],
+        syntax: filePath?.endsWith('.sass') ? 'indented' : 'scss',
+    });
+    return result.css;
+}
+// The indented Sass syntax and SCSS syntax share the one compiler entry point (`compileScss`'s
+// `syntax` option already picks between them off the file extension) — `compileSass` is just the
+// `.sass`-reading alias for it.
+export const compileSass = compileScss;
+/** Compiles Less down to plain CSS text. Less has no synchronous render API. */
+export async function compileLess(source, filePath) {
+    const less = await loadLess();
+    const result = await less.render(source, {
+        filename: filePath,
+        paths: filePath ? [path.dirname(filePath)] : [],
+    });
+    return result.css;
+}
+/** Compiles Stylus down to plain CSS text. Stylus's `render` is callback-based; wrapped in a
+ * Promise so it composes with the rest of this module's async API. */
+export async function compileStylus(source, filePath) {
+    const stylus = await loadStylus();
+    const compiler = stylus(source);
+    if (filePath)
+        compiler.set('filename', filePath);
+    return new Promise((resolve, reject) => {
+        compiler.render((error, css) => {
+            if (error)
+                reject(error);
+            else
+                resolve(css ?? '');
+        });
+    });
+}
+/** Unified entry point: reduces any recognized preprocessor language down to plain CSS text.
+ * `lang: 'css'` is a no-op passthrough — callers decide whether preprocessing is needed at all,
+ * typically via {@link detectLanguage}. */
+export async function compile(source, lang, filePath) {
+    switch (lang) {
+        case 'scss':
+            return compileScss(source, filePath);
+        case 'less':
+            return compileLess(source, filePath);
+        case 'stylus':
+            return compileStylus(source, filePath);
+        case 'css':
+            return source;
+    }
+}

package/build/properties.d.ts

@@ -0,0 +1,24 @@
+type IPropertyValueKind = 'number' | 'dimension' | 'raw';
+type IPropertyMapping = {
+    rnProperty: string;
+    kind: IPropertyValueKind;
+};
+/**
+ * kebab-case CSS property → { RN camelCase prop, value-conversion kind }.
+ * `dimension` = number-or-percent (`parseNumericOrPercent`); `number` = always a plain
+ * number (`parseNumeric`, no percent, e.g. `flexGrow`); `raw` = passthrough string
+ * (colors, font family, enum keywords like `flexDirection`).
+ */
+export declare const PROPERTY_TABLE: Record<string, IPropertyMapping>;
+/**
+ * Map one CSS declaration to its RN style entry. Returns `null` and warns once per unique
+ * unsupported property name (deduped via the caller-owned `warnedProperties` set, so the
+ * warning fires once per {@link parseCSS} call, not per occurrence).
+ *
+ * `text-shadow` bypasses {@link PROPERTY_TABLE}: RN has no unified CSS-string `textShadow` prop
+ * (unlike `transform`/`box-shadow` above) — only three separate legacy props
+ * (`textShadowColor`/`Offset`/`Radius`) that take already-decomposed values, so this package is
+ * the only place that CAN parse the CSS shorthand; there is no engine-level processor to defer to.
+ */
+export declare function mapCSSProperty(prop: string, value: string, warnedProperties: Set<string>): Record<string, unknown> | null;
+export {};

package/build/properties.js

@@ -0,0 +1,144 @@
+// 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.
+import { parseNumeric, parseNumericOrPercent, parseRawValue, parseTextShadow, warnOnce, } from "./values.js";
+/**
+ * kebab-case CSS property → { RN camelCase prop, value-conversion kind }.
+ * `dimension` = number-or-percent (`parseNumericOrPercent`); `number` = always a plain
+ * number (`parseNumeric`, no percent, e.g. `flexGrow`); `raw` = passthrough string
+ * (colors, font family, enum keywords like `flexDirection`).
+ */
+export const PROPERTY_TABLE = {
+    // Flexbox / layout
+    flex: { rnProperty: 'flex', kind: 'number' },
+    'flex-direction': { rnProperty: 'flexDirection', kind: 'raw' },
+    'flex-wrap': { rnProperty: 'flexWrap', kind: 'raw' },
+    'flex-grow': { rnProperty: 'flexGrow', kind: 'number' },
+    'flex-shrink': { rnProperty: 'flexShrink', kind: 'number' },
+    'flex-basis': { rnProperty: 'flexBasis', kind: 'dimension' },
+    'align-items': { rnProperty: 'alignItems', kind: 'raw' },
+    'align-self': { rnProperty: 'alignSelf', kind: 'raw' },
+    'align-content': { rnProperty: 'alignContent', kind: 'raw' },
+    'justify-content': { rnProperty: 'justifyContent', kind: 'raw' },
+    width: { rnProperty: 'width', kind: 'dimension' },
+    height: { rnProperty: 'height', kind: 'dimension' },
+    'min-width': { rnProperty: 'minWidth', kind: 'dimension' },
+    'min-height': { rnProperty: 'minHeight', kind: 'dimension' },
+    'max-width': { rnProperty: 'maxWidth', kind: 'dimension' },
+    'max-height': { rnProperty: 'maxHeight', kind: 'dimension' },
+    position: { rnProperty: 'position', kind: 'raw' },
+    top: { rnProperty: 'top', kind: 'dimension' },
+    right: { rnProperty: 'right', kind: 'dimension' },
+    bottom: { rnProperty: 'bottom', kind: 'dimension' },
+    left: { rnProperty: 'left', kind: 'dimension' },
+    'z-index': { rnProperty: 'zIndex', kind: 'number' },
+    overflow: { rnProperty: 'overflow', kind: 'raw' },
+    // Only `flex`/`none` are valid RN values; passed through unvalidated per spec.
+    display: { rnProperty: 'display', kind: 'raw' },
+    // A genuine 1:1 CSS property (unlike transform/shadow — no shape mismatch), just missing
+    // from the initial table. `2 / 3` string ratios are not accepted here (`parseNumeric`
+    // requires a plain number) — CSS `aspect-ratio: 0.667` works, `aspect-ratio: 2/3` doesn't yet.
+    'aspect-ratio': { rnProperty: 'aspectRatio', kind: 'number' },
+    gap: { rnProperty: 'gap', kind: 'dimension' },
+    'row-gap': { rnProperty: 'rowGap', kind: 'dimension' },
+    'column-gap': { rnProperty: 'columnGap', kind: 'dimension' },
+    // Passed through as raw CSS text, UNPARSED — RN's own JS pre-processors
+    // (`core/engine/src/process-transform`, ported from RN's `processTransform.js`) already parse
+    // this exact CSS-function-list syntax at commit time (`enableNativeCSSParsing()` defaults to
+    // `false`, so RN's stock path always runs this JS parse before native, regardless of what
+    // produced the string). Re-parsing it here would duplicate that logic and, being a narrower
+    // reimplementation, would regress real RN features (`matrix()`, `perspective()`,
+    // `translate3d()`) the engine's port already handles.
+    transform: { rnProperty: 'transform', kind: 'raw' },
+    // Same reasoning as `transform`: `core/engine/src/process-box-shadow` already parses this
+    // exact CSS syntax at commit time, including multi-shadow lists, `inset`, and spread-radius —
+    // all of which RN's native `boxShadow` prop genuinely supports (Fabric, both platforms).
+    'box-shadow': { rnProperty: 'boxShadow', kind: 'raw' },
+    // Same reasoning as `transform`/`box-shadow`: `core/engine/src/process-filter` already parses
+    // this exact CSS filter-function-list syntax (`brightness()`, `blur()`, `drop-shadow()`, …) at
+    // commit time, ported from RN's own `processFilter.js`.
+    filter: { rnProperty: 'filter', kind: 'raw' },
+    // Same reasoning again: `core/engine/src/process-transform-origin` already parses this exact
+    // CSS syntax (keyword/length/percentage pairs, e.g. `top left`, `50% 100%`) at commit time,
+    // ported from RN's own `processTransformOrigin.js`.
+    'transform-origin': { rnProperty: 'transformOrigin', kind: 'raw' },
+    // Same reasoning again: `core/engine/src/process-background-image` already parses this exact
+    // CSS gradient syntax (`linear-gradient(...)`/`radial-gradient(...)`) at commit time, ported
+    // from RN's own `processBackgroundImage.js`. RN's own style prop is itself named with an
+    // `experimental_` prefix (still evolving upstream), which is why the RN key doesn't just
+    // match a kebab→camel rename of the CSS property the way every other entry here does.
+    'background-image': { rnProperty: 'experimental_backgroundImage', kind: 'raw' },
+    // Spacing
+    margin: { rnProperty: 'margin', kind: 'dimension' },
+    'margin-top': { rnProperty: 'marginTop', kind: 'dimension' },
+    'margin-right': { rnProperty: 'marginRight', kind: 'dimension' },
+    'margin-bottom': { rnProperty: 'marginBottom', kind: 'dimension' },
+    'margin-left': { rnProperty: 'marginLeft', kind: 'dimension' },
+    padding: { rnProperty: 'padding', kind: 'dimension' },
+    'padding-top': { rnProperty: 'paddingTop', kind: 'dimension' },
+    'padding-right': { rnProperty: 'paddingRight', kind: 'dimension' },
+    'padding-bottom': { rnProperty: 'paddingBottom', kind: 'dimension' },
+    'padding-left': { rnProperty: 'paddingLeft', kind: 'dimension' },
+    // Border
+    'border-width': { rnProperty: 'borderWidth', kind: 'dimension' },
+    'border-top-width': { rnProperty: 'borderTopWidth', kind: 'dimension' },
+    'border-right-width': { rnProperty: 'borderRightWidth', kind: 'dimension' },
+    'border-bottom-width': { rnProperty: 'borderBottomWidth', kind: 'dimension' },
+    'border-left-width': { rnProperty: 'borderLeftWidth', kind: 'dimension' },
+    'border-color': { rnProperty: 'borderColor', kind: 'raw' },
+    'border-top-color': { rnProperty: 'borderTopColor', kind: 'raw' },
+    'border-right-color': { rnProperty: 'borderRightColor', kind: 'raw' },
+    'border-bottom-color': { rnProperty: 'borderBottomColor', kind: 'raw' },
+    'border-left-color': { rnProperty: 'borderLeftColor', kind: 'raw' },
+    'border-radius': { rnProperty: 'borderRadius', kind: 'dimension' },
+    'border-top-left-radius': { rnProperty: 'borderTopLeftRadius', kind: 'dimension' },
+    'border-top-right-radius': { rnProperty: 'borderTopRightRadius', kind: 'dimension' },
+    'border-bottom-left-radius': { rnProperty: 'borderBottomLeftRadius', kind: 'dimension' },
+    'border-bottom-right-radius': { rnProperty: 'borderBottomRightRadius', kind: 'dimension' },
+    'border-style': { rnProperty: 'borderStyle', kind: 'raw' },
+    // Visual
+    'background-color': { rnProperty: 'backgroundColor', kind: 'raw' },
+    opacity: { rnProperty: 'opacity', kind: 'number' },
+    // Text
+    color: { rnProperty: 'color', kind: 'raw' },
+    'font-size': { rnProperty: 'fontSize', kind: 'dimension' },
+    'font-weight': { rnProperty: 'fontWeight', kind: 'raw' },
+    'font-family': { rnProperty: 'fontFamily', kind: 'raw' },
+    'font-style': { rnProperty: 'fontStyle', kind: 'raw' },
+    'text-align': { rnProperty: 'textAlign', kind: 'raw' },
+    'text-decoration-line': { rnProperty: 'textDecorationLine', kind: 'raw' },
+    'line-height': { rnProperty: 'lineHeight', kind: 'dimension' },
+    'letter-spacing': { rnProperty: 'letterSpacing', kind: 'dimension' },
+};
+function convertValue(kind, value) {
+    switch (kind) {
+        case 'number':
+            return parseNumeric(value);
+        case 'dimension':
+            return parseNumericOrPercent(value);
+        case 'raw':
+            return parseRawValue(value);
+    }
+}
+/**
+ * Map one CSS declaration to its RN style entry. Returns `null` and warns once per unique
+ * unsupported property name (deduped via the caller-owned `warnedProperties` set, so the
+ * warning fires once per {@link parseCSS} call, not per occurrence).
+ *
+ * `text-shadow` bypasses {@link PROPERTY_TABLE}: RN has no unified CSS-string `textShadow` prop
+ * (unlike `transform`/`box-shadow` above) — only three separate legacy props
+ * (`textShadowColor`/`Offset`/`Radius`) that take already-decomposed values, so this package is
+ * the only place that CAN parse the CSS shorthand; there is no engine-level processor to defer to.
+ */
+export function mapCSSProperty(prop, value, warnedProperties) {
+    if (prop === 'text-shadow')
+        return parseTextShadow(value, warnedProperties);
+    const mapping = PROPERTY_TABLE[prop];
+    if (!mapping) {
+        warnOnce(warnedProperties, prop, `[@symbiote-native/css-parser] unsupported CSS property "${prop}" dropped`);
+        return null;
+    }
+    return { [mapping.rnProperty]: convertValue(mapping.kind, value) };
+}

package/build/values.d.ts

@@ -0,0 +1,27 @@
+declare const REM_TO_PX = 16;
+/**
+ * Convert a CSS dimension to a plain number: strips `px`, scales `rem`/`em` by
+ * {@link REM_TO_PX}, and passes unitless numbers through untouched.
+ */
+export declare function parseNumeric(value: string): number;
+/**
+ * Same as {@link parseNumeric}, except a percentage value is kept as a string
+ * (`'50%'`) — RN accepts percentage strings for most layout props.
+ */
+export declare function parseNumericOrPercent(value: string): number | string;
+/**
+ * Colors, font families, and CSS keyword values (`'bold'`, `'row'`, `'red'`) pass through
+ * unchanged — RN accepts the same raw strings CSS does for these props.
+ */
+export declare function parseRawValue(value: string): string;
+/**
+ * Warn once per unique `key` across a {@link parseCSS} call (the caller-owned `warned` set is
+ * shared with the plain-property drop warning in properties.ts, so every "unsupported X dropped"
+ * message in this package dedupes the same way).
+ */
+export declare function warnOnce(warned: Set<string>, key: string, message: string): void;
+/** `text-shadow` → RN's `textShadowColor`/`textShadowOffset`/`textShadowRadius` (no Android
+ * elevation equivalent — RN has no elevation concept for text, and no engine-level processor
+ * to defer to the way `box-shadow` does — see the PROPERTY_TABLE comment in properties.ts). */
+export declare function parseTextShadow(value: string, warned: Set<string>): Record<string, unknown> | null;
+export { REM_TO_PX };