dot 개요
stable크로스 플랫폼 스타일 엔진 — 유틸리티 문자열을 CSS/네이티브 스타일로 변환
패키지 개요
@hua-labs/dot는 Tailwind에서 영감을 받은 유틸리티 문자열을 플랫 스타일 오브젝트로 변환하는 크로스 플랫폼 스타일 엔진입니다. 웹(CSSProperties), React Native(StyleSheet), Flutter(FlutterRecipe)를 단일 파이프라인으로 지원합니다. 의존성이 없으며 1176개 이상의 테스트를 통과합니다.
핵심 개념
유틸리티 문자열은 공백으로 구분된 토큰으로 구성됩니다. dot() 함수는 각 토큰을 파싱하고 대상 플랫폼에 맞는 스타일 오브젝트로 변환합니다.
import { dot } from '@hua-labs/dot';
// 유틸리티 문자열 → CSSProperties (웹)
dot('p-4 flex items-center bg-primary-500 text-white rounded-lg');
// { padding: '16px', display: 'flex', alignItems: 'center', ... }
// React Native 대상
dot('p-4 rounded-lg', { target: 'native' });
// { padding: 16, borderRadius: 8 }
// Flutter 대상
dot('p-4 bg-blue-500 rounded-lg', { target: 'flutter' });
// FlutterRecipe { padding: { top: 16, ... }, decoration: { color: '#3b82f6', ... } }Entry Points
| Entry Point | 설명 |
|---|---|
@hua-labs/dot | 메인 — 웹/네이티브/Flutter 전체 지원 |
@hua-labs/dot/class | 클래스 모드 — CSS 클래스 이름 생성 (해시 기반) |
@hua-labs/dot/native | React Native 전용 — target: 'native' 사전 바인딩 |
주요 API
| 함수 | 설명 |
|---|---|
dot() | 유틸리티 문자열 → 플랫 스타일 오브젝트 |
dotMap() | 유틸리티 문자열 → base + 상태 변형(hover/focus/active) 맵 |
dotClass() | 유틸리티 문자열 → CSS 클래스 이름 (해시 기반) |
dotCSS() | 유틸리티 문자열 → { className, css } |
dotVariants() | CVA 스타일 변형 빌더 |
dotCx() | clsx 대체 — falsy 값 필터링 후 유틸리티 문자열 결합 |
dotExplain() | 스타일 해석 + 플랫폼 호환성 보고서 |
createDotConfig() | 글로벌 토큰 설정 재정의 |
clearDotCache() | 입력/토큰 캐시 초기화 |
semanticVars() | CSS 변수 기반 시맨틱 색상 매핑 생성 |
주요 기능
반응형 (Responsive)
모바일 퍼스트 캐스케이드 방식으로 반응형 변형을 지원합니다. 기본 브레이크포인트: sm, md, lg, xl, 2xl.
dot('p-4 md:p-8 lg:p-12', { breakpoint: 'lg' });
// { padding: '48px' } ← base → md → lg 캐스케이드다크 모드
dark: 접두사로 다크 모드 스타일을 조건부로 적용합니다.
dot('bg-white dark:bg-gray-900 text-black dark:text-white', { dark: true });
// { backgroundColor: '#111827', color: '#ffffff' }상태 변형 (State Variants)
dotMap()으로 hover/focus/active 등 상태별 스타일 버킷을 분리합니다.
dotMap('bg-white hover:bg-gray-100 focus:ring-2');
// { base: { backgroundColor: '#ffffff' }, hover: { backgroundColor: '#f3f4f6' }, focus: { boxShadow: '...' } }Arbitrary Values
[...] 구문으로 임의의 값을 지정합니다.
dot('w-[300px] bg-[#ff0000] p-[2rem]');
// { width: '300px', backgroundColor: '#ff0000', padding: '2rem' }투명도 수정자 (Opacity Modifier)
/ 구문으로 색상에 불투명도를 지정합니다.
dot('bg-primary-500/50 text-gray-900/80');
// { backgroundColor: 'rgb(59 130 246 / 0.5)', color: 'rgb(17 24 39 / 0.8)' }!important 수정자
! 접두사로 !important를 적용합니다.
dot('!p-4 !bg-white');
// { padding: '16px !important', backgroundColor: '#ffffff !important' }플랫폼 지원 수준 (Capability Matrix)
| 유틸리티 패밀리 | 웹 | React Native | Flutter |
|---|---|---|---|
| spacing / color / typography | native | native | native |
| flexbox / border / borderRadius | native | native | native |
| shadow | native | approximate | native |
| transform | native | native | native |
| transition / animation | native | unsupported | unsupported |
| filter / backdropFilter | native | unsupported | plugin-backed |
| grid | native | unsupported | recipe-only |
| gradient | native | unsupported | recipe-only |
| interactivity | native | unsupported | unsupported |
리졸버 패밀리
33개 리졸버 패밀리를 지원합니다: spacing, colors, typography, layout, sizing, border, flexbox, z-index, shadow, opacity, transform, transition, animation, backdrop, positioning, grid, ring, filter, interactivity, line-clamp, mix-blend, gradient, object-fit, float, table, list, scroll, touch-action, will-change, word-break, isolation, bg-clip, font-smoothing, divide.
Notes
- 2계층 FIFO 캐시(입력 레벨 500 + 토큰 레벨 1000)로 반복 호출 성능을 최적화합니다.
createDotConfig()호출 후 반드시clearDotCache()를 호출하거나createDotConfig()가 내부적으로 캐시를 재생성합니다.@hua-labs/dot/class의 클래스 모드는 반응형(sm:,md:), hover, focus, pseudo-element 등 인라인 스타일로 표현할 수 없는 CSS 기능에 사용합니다.