Skip to content

feat(stylex): support StyleX styleResolution option - #981

Open
owjs3901 wants to merge 4 commits into
fix/css-later-shorthand-winsfrom
feat/stylex-style-resolution
Open

owjs3901 wants to merge 4 commits into
fix/css-later-shorthand-winsfrom
feat/stylex-style-resolution

Conversation

@owjs3901

@owjs3901 owjs3901 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This PR is stacked on #978 (#978 is stacked on #974). Its base is #978's branch fix/css-later-shorthand-wins. After #974 and then #978 are merged, this PR's base must be changed to main.

Supports the StyleX babel plugin's styleResolution option (SX-13). Until now the docs only stated that the default (property-specificity) was used.

Option

  • Every plugin (vite, rsbuild, webpack, next, bun) accepts stylex: { styleResolution }.
    DevupUI({ stylex: { styleResolution: 'application-order' } })
  • Path: plugin option → normalizeStylexOptions() in @devup-ui/plugin-utils → new binding export setStylexStyleResolution() (both WASM and NAPI) → the css::style_resolution global → the extractor's StyleX path.
    • It is set at the same point as registerShorthands. Next Turbopack passes the option in the coordinator process, and Next webpack passes it through the webpack plugin. It is also included in the production setup handoff key.
  • The default is 'property-specificity'.
  • An unknown value throws StylexConfigError when the plugin is created, before a compiler is chosen. Passing it directly to the binding also produces an error for the same reason on the Rust side.
  • resetBuildState keeps this setting, like shorthands. resetStateForTesting restores the default.

Behavior by policy (static stylex.create() namespace)

The expansions tables of StyleX 0.19.1 @stylexjs/babel-plugin were generated from source and carried over as-is (libs/extractor/src/stylex_resolution_tables.rs).

  • property-specificity (default): nothing is expanded. Thanks to fix(sheet): write a longhand after every shorthand that covers it #974's sheet order (longhands after shorthands), the longhand wins regardless of order. Existing output does not change.
  • application-order: like StyleX, a shorthand key gets null resets for the longhand keys it covers.
    • In stylex.props(s.top, s.pad), the later padding clears padding-top. In the reverse order both remain and padding-top wins by sheet order. As a result, whatever is applied last wins.
    • The same holds within one namespace: with { paddingTop, padding } only padding remains.
    • Aliases from the tables are read as well: marginStart → margin-inline-start, blockSize → height, left/right ↔ insetInline* resets.
  • legacy-expand-shorthands: shorthands are split into longhands at build time.
    • padding: '1px 2px' → padding-top, padding-inline-end, padding-bottom, padding-inline-start.
    • Follows StyleX's splitValue: the inside of functions and strings is not split, and a trailing !important is attached to each part.
    • containIntrinsicSize (combining auto 10px) and listStyle (type/position/image classification) are also handled by StyleX's rules.
  • Common
    • Value conditions (default, :hover, @media) are expanded per condition. Keys inside a top-level ':hover': {...} object are expanded too.
    • In a static namespace, a later key with the same name replaces the earlier key in place (JS object semantics). This is independent of the policy, but needed because expanded keys overlap each other.
    • Cases where StyleX throws are reported as build errors naming the key: a firstThatWorks() fallback on a shorthand, all under application-order, and an unsplittable listStyle under legacy-expand-shorthands. The StyleX default (propertyValidationMode: 'silent') silently drops these keys; here they are reported as errors.
    • The existing [stylex] WARNING: Shorthand property warning is printed only under property-specificity.

Not covered

Docs, changepack

  • Added a "Shorthands and styleResolution" section to docs/migration/stylex. docs(landing): state StyleX resolution policy and legacy include() #969 also adds a resolution policy explanation to the same page. Whichever is merged later must combine those sections into one.
  • changepack: @devup-ui/wasm, @devup-ui/binding, plugin-utils, vite/rsbuild/webpack/next/bun plugin (Patch)

Overlapping PRs

Test plan

  • extractor::stylex_resolution unit tests: per-policy tables, splitValue, box/pair defaults, !important, containIntrinsicSize, listStyle classification and errors, and that every table name is camelCase
  • extractor::stylex_resolution_extract_tests: verified through real extraction
    • stylex.props() merging in both directions: under all three policies
    • Replacement within a namespace, aliases, per-condition expansion, :hover objects, kebab keys
    • null shorthand resets, the 3 build errors, longhand fallbacks kept
  • css::style_resolution: name parsing, an unknown value is an error and the existing policy is kept; the test-state guard saves and restores it
  • devup-ui-wasm: set_stylex_style_resolution_internal
  • cargo test -p css -p extractor -p devup-ui-binding-core -p devup-ui-wasm --tests -j 2 passes
  • cargo clippy -p css -p extractor -p devup-ui-binding-core -p devup-ui-wasm -p devup-ui-binding --all-targets -- -D warnings, cargo fmt --all
  • bun: plugin-utils stylex-options.test.ts, wasm-abi.test.ts (export list and actual WASM behavior), setup/rejection tests for the five plugins
  • e2e binding: export list (host.mjs), argument validation slot, valid/unknown/malformed scenarios added to the native/WASM comparison corpus
  • CI coverage (Rust 100%, bun 100%)

#978 위에 쌓은 PR입니다 (#978은 #974 위에 쌓여 있습니다). base는 #978의 브랜치 fix/css-later-shorthand-wins입니다. #974 → #978 순서로 merge된 뒤 이 PR의 base를 main으로 바꿔야 합니다.

요약

StyleX babel plugin의 styleResolution 옵션을 지원합니다(SX-13). 지금까지는 기본값(property-specificity)만 쓴다고 문서에 적었을 뿐입니다.

옵션

  • 모든 plugin(vite, rsbuild, webpack, next, bun)이 stylex: { styleResolution }을 받습니다.
    DevupUI({ stylex: { styleResolution: 'application-order' } })
  • 경로: plugin 옵션 → @devup-ui/plugin-utils의 normalizeStylexOptions() → 새 binding export setStylexStyleResolution()(WASM, NAPI 둘 다) → css::style_resolution 전역 → extractor의 StyleX 경로.
    • registerShorthands와 같은 시점에 설정합니다. Next Turbopack은 coordinator 프로세스에서, Next webpack은 webpack plugin으로 옵션을 넘깁니다. production setup handoff key에도 넣었습니다.
  • 기본값은 'property-specificity'입니다.
  • 알 수 없는 값은 plugin 생성 시 StylexConfigError를 던집니다. compiler를 고르기 전입니다. binding에 직접 넘겨도 Rust 쪽에서 같은 이유의 오류가 납니다.
  • resetBuildState는 shorthands처럼 이 설정을 유지합니다. resetStateForTesting은 기본값으로 되돌립니다.

정책별 동작 (static stylex.create() namespace)

StyleX 0.19.1 @stylexjs/babel-plugin의 expansions 표를 소스에서 생성해 그대로 옮겼습니다(libs/extractor/src/stylex_resolution_tables.rs).

  • property-specificity (기본): 아무것도 펼치지 않습니다. #974의 sheet 순서(longhand가 shorthand 뒤) 덕분에 순서와 관계없이 longhand가 이깁니다. 기존 출력은 바뀌지 않습니다.
  • application-order: StyleX처럼 shorthand key에 그것이 덮는 longhand key의 null reset을 붙입니다.
    • stylex.props(s.top, s.pad)에서는 뒤의 padding이 padding-top을 지웁니다. 반대 순서면 둘 다 남고 sheet 순서로 padding-top이 이깁니다. 결과적으로 마지막에 적용한 것이 이깁니다.
    • 한 namespace 안에서도 같습니다: { paddingTop, padding }이면 padding만 남습니다.
    • 표의 alias도 읽습니다: marginStart → margin-inline-start, blockSize → height, left/right ↔ insetInline* reset.
  • legacy-expand-shorthands: shorthand를 빌드 시점에 longhand로 나눕니다.
    • padding: '1px 2px' → padding-top, padding-inline-end, padding-bottom, padding-inline-start.
    • StyleX의 splitValue를 따릅니다: 함수·문자열 안은 나누지 않고, 끝의 !important는 각 부분에 붙습니다.
    • containIntrinsicSize(auto 10px 결합)와 listStyle(type/position/image 분류)도 StyleX 규칙대로 처리합니다.
  • 공통
    • 값의 조건(default, :hover, @media)은 조건별로 펼칩니다. 최상위 ':hover': {...} 객체 안의 key도 펼칩니다.
    • static namespace에서 같은 이름의 뒤 key가 앞 key를 그 자리에서 대체합니다(JS 객체 의미). 정책과 무관하지만 펼친 key끼리 겹치기 때문에 필요합니다.
    • StyleX가 throw하는 경우는 key 이름을 담은 빌드 오류로 냅니다: shorthand에 firstThatWorks() fallback, application-order의 all, legacy-expand-shorthands에서 나눌 수 없는 listStyle. StyleX 기본값(propertyValidationMode: 'silent')은 이 key를 조용히 버리는데, 여기서는 오류로 알립니다.
    • property-specificity에서만 기존 [stylex] WARNING: Shorthand property 경고를 찍습니다.

다루지 않는 것

  • dynamic(arrow function) namespace: 펼치지 않고 shorthand를 그대로 씁니다. 런타임 값은 나눌 수 없고, devup의 dynamic namespace는 key 단위로 병합하지 않습니다.
  • legacy의 float/clear 논리값(inline-start 등): 값 그대로 둡니다. StyleX의 polyfill은 자체 런타임 변수(--stylex-logical-start)에 기대기 때문입니다.
  • kebab-case key('padding-block'): StyleX 표처럼 camelCase key만 펼칩니다. 'padding'처럼 둘의 철자가 같은 key는 펼칩니다.
  • 최상위 pseudo 객체 사이의 병합: ':hover' 객체는 지금처럼 하나의 key로 병합합니다. StyleX는 :hover_paddingTop처럼 속성별로 병합합니다. 같은 객체 안의 reset/대체는 적용됩니다.
  • include() 병합(fix(extractor): let later StyleX keys override an include() #975)과는 아직 엮지 않았습니다. #975가 merge되면 포함된 namespace의 key도 같은 표를 거치는지 확인해야 합니다.
  • Devup 자체 API(css(), styled, Box props)는 옵션을 무시하고 [전수조사/A] 조합 우선순위: 뒤에 쓴 스타일이 이기게 (빌드 타임 정적 해결) #688/fix(extractor): let a later shorthand replace the longhands it covers #978 동작을 유지합니다.

문서, changepack

  • docs/migration/stylex에 "Shorthands and styleResolution" 절을 추가했습니다. #969도 같은 페이지에 resolution 정책 설명을 추가합니다. 둘 중 나중에 merge되는 쪽에서 해당 절을 하나로 합쳐야 합니다.
  • changepack: @devup-ui/wasm, @devup-ui/binding, plugin-utils, vite/rsbuild/webpack/next/bun plugin (Patch)

겹치는 PR

테스트 계획

  • extractor::stylex_resolution 단위 테스트: 정책별 표, splitValue, box/pair 기본값, !important, containIntrinsicSize, listStyle 분류와 오류, 표 이름이 모두 camelCase인지
  • extractor::stylex_resolution_extract_tests: 실제 추출로 확인
    • stylex.props() 양방향 병합: 세 정책 모두
    • namespace 안의 대체, alias, 조건별 전개, :hover 객체, kebab key
    • null shorthand reset, 빌드 오류 3종, longhand fallback 유지
  • css::style_resolution: 이름 파싱, 알 수 없는 값은 오류이고 기존 정책 유지. test-state guard가 저장·복원하는지
  • devup-ui-wasm: set_stylex_style_resolution_internal
  • cargo test -p css -p extractor -p devup-ui-binding-core -p devup-ui-wasm --tests -j 2 통과
  • cargo clippy -p css -p extractor -p devup-ui-binding-core -p devup-ui-wasm -p devup-ui-binding --all-targets -- -D warnings, cargo fmt --all
  • bun: plugin-utils stylex-options.test.ts, wasm-abi.test.ts(export 목록과 실제 WASM 동작), 다섯 plugin의 설정·거부 테스트
  • e2e binding: export 목록(host.mjs), argument validation slot, native/WASM 비교 corpus에 valid/unknown/malformed 시나리오 추가
  • CI 커버리지 (Rust 100%, bun 100%)

Refs #690

🤖 Generated with Claude Code

owjs3901 and others added 4 commits November 16, 2026 03:36
Every plugin takes `stylex: { styleResolution }`, StyleX's babel plugin
option, validated before setup (`StylexConfigError`) and handed to the
engine through the new `setStylexStyleResolution()` binding export.

- `property-specificity` (default) expands nothing: the sheet writes a
  longhand after its shorthands (#974).
- `application-order` gives a static `create()` key the `null` resets
  StyleX's table lists, and reads its aliases, so the key applied last wins
  in `stylex.props()` and within a namespace.
- `legacy-expand-shorthands` splits a shorthand into its longhands as
  StyleX's table does, `!important`, `containIntrinsicSize` and `listStyle`
  included.

Both tables are generated from @stylexjs/babel-plugin 0.19.1. A later key
of a static namespace replaces an earlier one of the same name. Dynamic
namespaces and `float`/`clear` logical values stay as written. Devup UI's
own APIs ignore the option.

Refs #690

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in main through #974 and #978. In the vite, rsbuild, webpack and
bun plugins, the setupWarning (#945) imports and main's
createNodeModulesExcludeRegex sit beside normalizeStylexOptions, and
styleResolution is still set next to registerShorthands wherever main
configures the engine.

The ABI now has 31 names: main's removeFile plus
setStylexStyleResolution. Updated the count in script.js, the consumer,
the native README and typings, and compiler-types (30 without Output).
Validation covers 47 positions in 20 functions (276 cases), and the
summary reports 20 functions. The e2e host lists both names and
counts 27 corpus scenarios.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in main through the base branch. Its merge with main (0e409e3,
9f46158) already resolved property_order.rs,
extract_style_from_expression.rs, the style_results_read_as_values
snapshot and sheet/lib.rs against #974, so this merge applies cleanly
and origin/main adds nothing beyond it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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