Skip to content

Unify CSS-to-RN compiler and runtime pipeline#5

Draft
cray0000 wants to merge 32 commits into
masterfrom
unification
Draft

Unify CSS-to-RN compiler and runtime pipeline#5
cray0000 wants to merge 32 commits into
masterfrom
unification

Conversation

@cray0000

@cray0000 cray0000 commented Jun 20, 2026

Copy link
Copy Markdown
Member

Summary

This PR unifies the CSS-to-React-Native style pipeline into a new @cssxjs/css-to-rn workspace package and wires CSSX, loaders, Babel output, and runtime entrypoints through it. The goal is to replace the separate forked CSS-to-RN transform libraries and the old CSSX runtime with one maintainable compiler/runtime package.

Key changes:

  • Adds packages/css-to-rn, a TypeScript ESM package owning CSS parsing, selector IR, value resolution, property transforms, style resolution, caching, and React runtime tracking.
  • Keeps Stylus-to-CSS compilation separate, while moving pure CSS-to-RN style compilation and runtime resolution into the unified package.
  • Supports local JS template interpolation in function-scoped css/styl templates, with interpolation values reusing one cache slot per compiled call shape.
  • Adds runtime CSS string compilation for generated CSS via useRuntimeCss(), useCssxLayer(), and cssx().
  • Implements nested var() resolution, partial shorthand substitution, dynamic dependency tracking, bounded cache behavior, deep inline-style hashing, media/dimension tracking, web matchMedia invalidation, and React Native Dimensions integration.
  • Adds React 19 tracking without Teamplay or @nx-js/observer-util, including Suspense/aborted-render cleanup tests.
  • Adds CssxProvider style and theme for subtree-scoped provider CSS, global utility classes, scoped :root / :root.<theme> variables, OS dark-mode auto selection, and component tag overrides.
  • Adds CSSX theme assets and exports: cssxjs/themes/tailwind and cssxjs/themes/shadcn.
  • Adds @custom-media, CSS media range evaluation for width/height comparisons, built-in @media (--theme-*) aliases, and provider-aware useMedia().
  • Adds component tag selectors through themed(tagName, Component), including Tag, Tag.class, Tag:part(name), Tag::part(name), Tag:hover, and Tag:active matching.
  • Adds useCssVariable(), useCssVariableRaw(), getCssVariable(), and getCssVariableRaw() for subscribed and global JS access to resolved CSS variables.
  • Adds useCssColor() and getCssColor() for provider-aware JS color bridges, including token lookup and color-mix() style mixing.
  • Adds a deprecated JS u() helper and build diagnostics for deprecated CSS u units.
  • Adds validating variables and defaultVariables proxy methods: .assign(), .set(), and .clear().
  • Resolves var() inside inline style props and tracks the variables used by those inline props.
  • Normalizes oklch(), oklab(), and color-mix() through pinned @colordx/core@5.4.3 so modern color CSS works on RN.
  • Supports percentage/unitless calc() in CSS value resolution for color-channel math while still rejecting mixed layout calc such as calc(100% - 16px).
  • Mixes color-mix(in srgb, color, transparent) with premultiplied alpha so transparent theme colors preserve the source RGB.
  • Preserves source-condition TypeScript consumers without committing build output: source entrypoints carry vendor shims, themed() preserves wrapped component props, and cssx() accepts loader-produced opaque sheet records at the type boundary.
  • Implements :hover/:active aliases, filter, background-image/gradient support, limited background shorthand, animations/transitions/keyframes, and Reanimated v4-compatible animation style output.
  • Adds build-strict diagnostics for unsupported static declarations while keeping runtime compilation graceful for generated CSS.
  • Migrates loaders and Babel runtime paths to the unified package, with source-condition test/dev imports and facade smoke coverage.
  • Stops tracking generated dist output; package builds still emit dist for published/default exports.
  • Keeps legacy runtime/*-teamplay import paths as compatibility wrappers only.
  • Removes the old packages/runtime package from the active graph.
  • Updates architecture.md, AGENTS.md, plan.md, public docs, README credits, and CI smoke checks for the new architecture.

Architect Review Follow-up

After a multi-agent architecture/performance/test-coverage review, this PR now also:

  • avoids promoting changed tracked sheets, interpolation values, or hook dependencies from Suspense-aborted renders
  • keeps useCssxLayer(false) hook order stable when toggled to a real sheet
  • allows and resolves template interpolation inside provider :root custom property values
  • resolves provider root variables from compiled sheets and { sheet, values } layers
  • adds regression coverage for complex partial var() values in box-shadow/filter/text-shadow/transform/background
  • updates runtime docs for precompiled provider :root interpolation

Related PRs

Validation

  • cd packages/css-to-rn && npm test
  • yarn test
  • yarn docs-build
  • git diff --check
  • Cross-repo validation with local source links for StartupJS and StartupJS UI provider/theme integration.
  • startupjs-ui PR validation: node scripts/check-startupjs-ui-exports.mjs, yarn install --immutable --mode=skip-build, targeted eslint, and direct CSS-template compile smoke over packages/ plus startupjsUiTheme.cssx.css.
  • startupjs PR validation: NODE_OPTIONS="-C cssx-ts" npm test in core/startupjs, plus the normal pre-commit hook with eslint and npx startupjs check.

Review Focus

This is a large architectural PR. Please scrutinize:

  • Runtime cache invalidation, interpolation cache behavior, and reference stability.
  • Provider :root / :root.<theme> variable scoping and precedence relative to runtime/default variables.
  • Theme selection, OS color-scheme subscriptions, and @media (--theme-*) behavior.
  • @custom-media, range media evaluation, and useMedia() subscriptions.
  • Component tag selector matching and the themed() render-local tracking model.
  • useCssVariable() / useCssColor() exact subscriptions and Suspense/aborted-render safety.
  • Media/dimension invalidation, web matchMedia subscriptions, React Native dimensions, and listener cleanup.
  • Complex value parsing: nested var(), shorthand fragments, modern colors, gradients/backgrounds, transforms, animations, transitions, and invalid generated CSS.
  • Babel output compatibility with existing CSSX styleName, css, styl, and part workflows.
  • Package exports/source-condition behavior and whether the new package boundary is maintainable long term.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant