# @hua-labs/dot - AI Documentation # Version: 0.2.0 # Auto-generated by generate-docs — do not edit manually package: name: "@hua-labs/dot" version: "0.2.0" description: "Cross-platform style engine — utility strings to Web CSSProperties / RN StyleSheet / Swift / Compose" license: "MIT" overview: "Cross-platform utility style engine for Web, React Native, and Flutter. Parses Tailwind-inspired utility strings into flat style objects via a shared resolver pipeline and target-specific adapters. Zero dependencies, framework-agnostic, 1176+ tests. ~90% Tailwind parity across 33 resolver families." exports: main: path: "@hua-labs/dot" provides: - name: "parse" type: "function" description: "" - name: "CAPABILITY_MATRIX" type: "component" description: "Static constant: Record>>. Maps utility family name (e.g. 'gradient', 'filter') to support level per target. Support levels: 'native' | 'approximate' | 'recipe-only' | 'plugin-backed' | 'unsupported'." - name: "PROPERTY_TO_FAMILY" type: "component" description: "Static constant: Record. Maps CSS property name (e.g. 'backgroundImage') to utility family name (e.g. 'gradient') for use with CAPABILITY_MATRIX." - name: "getCapability" type: "function" description: "getCapability(property, target, value?) → CapabilityLevel. Programmatic per-property capability query. Checks value-level overrides first (e.g. display:flex is 'native' on RN), then family-level lookup." - name: "adaptNative" type: "function" description: "Convert web CSSProperties to RN StyleSheet format. px→number, transform→array, boxShadow→RN shadow props, 45+ unsupported props silently dropped. Supports warnDropped option for dev warnings." - name: "_resetNativeWarnings" type: "function" description: "Reset native adapter warning dedup set. For testing only." - name: "adaptWeb" type: "function" description: "Identity adapter for web — returns input as-is. Used for symmetry with adaptNative." - name: "adaptFlutter" type: "function" description: "Convert web CSSProperties to FlutterRecipe — structured output mapping to Flutter widget composition (BoxDecoration, EdgeInsets, TextStyle, Matrix4, etc.). Options: { remBase?: number }. Gradient backgroundImage is mapped to FlutterGradient inside decoration." - name: "dotCx" type: "function" description: "clsx replacement — filters falsy values and joins utility strings. No style computation." - name: "dotVariants" type: "function" description: "CVA-style variant system. Accepts base, variants, defaultVariants, compoundVariants. Returns function that produces StyleObject." - name: "StyleObject" type: "type" description: "" - name: "DotToken" type: "type" description: "" - name: "DotUserConfig" type: "type" description: "" - name: "DotConfig" type: "type" description: "" - name: "DotOptions" type: "type" description: "" - name: "DotTarget" type: "type" description: "" - name: "DotState" type: "type" description: "" - name: "DotStyleMap" type: "type" description: "" - name: "ResolverFn" type: "type" description: "" - name: "ResolvedTokens" type: "type" description: "" - name: "RNStyleObject" type: "type" description: "" - name: "RNStyleValue" type: "type" description: "" - name: "RNTransformEntry" type: "type" description: "" - name: "RNShadowOffset" type: "type" description: "" - name: "CapabilityLevel" type: "type" description: "" - name: "TargetCapability" type: "type" description: "" - name: "DotCapabilityReport" type: "type" description: "" - name: "AdaptNativeOptions" type: "type" description: "" - name: "AdaptFlutterOptions" type: "type" description: "" - name: "FlutterRecipe" type: "type" description: "" - name: "FlutterDecoration" type: "type" description: "" - name: "FlutterEdgeInsets" type: "type" description: "" - name: "FlutterConstraints" type: "type" description: "" - name: "FlutterLayout" type: "type" description: "" - name: "FlutterFlexChild" type: "type" description: "" - name: "FlutterPositioning" type: "type" description: "" - name: "FlutterTextStyle" type: "type" description: "" - name: "FlutterTransform" type: "type" description: "" - name: "FlutterBoxShadow" type: "type" description: "" - name: "FlutterBorderSide" type: "type" description: "" - name: "FlutterBorderRadius" type: "type" description: "" - name: "VariantProps" type: "type" description: "" - name: "DotVariantsConfig" type: "type" description: "" - name: "DotVariantsFn" type: "type" description: "" - name: "CompoundVariant" type: "type" description: "" - name: "VariantShape" type: "type" description: "" - name: "dot" type: "function" description: "Convert utility string to flat style object. Type-safe overloads narrow return type by target literal: dot(input, { target: 'native' }) → RNStyleObject, dot(input, { target: 'flutter' }) → FlutterRecipe, dot(input) → StyleObject. Options: { dark?: boolean, breakpoint?: string, target?: 'web' | 'native' | 'flutter' }" - name: "dotExplain" type: "function" description: "Resolve a utility string and return both styles and a capability report. Returns DotExplainResult { styles, report: { _dropped?, _approximated?, _capabilities?, _details? } }. For web target returns empty report. Useful for debugging cross-platform compatibility." - name: "createDotConfig" type: "function" description: "Set global token configuration with deep merge. Accepts theme overrides (colors, spacing, borderRadius, fontSize, gridCols), runtime target, breakpoints (custom array), remBase, cache settings, strictMode, warnUnknown." - name: "clearDotCache" type: "function" description: "Clear both input and token caches. Call after config changes or for memory management." - name: "dotMap" type: "function" description: "Convert utility string to style map with state variants. Same type-safe overloads as dot(). Returns { base, hover?, focus?, active?, 'focus-visible'?, 'focus-within'?, disabled? }" - name: "semanticVars" type: "function" description: "Generate semantic color token mappings for use with createDotConfig. Maps token names to CSS variable references (e.g. 'background' → 'var(--color-background)'). Accepts an optional { prefix } object as the first argument to override the default '--color' prefix." features: - "dot() — utility string → CSSProperties (or RN StyleSheet / FlutterRecipe via adapter)" - "33 resolver families — 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" - "Arbitrary values — w-[300px], bg-[#ff0000], p-[2rem]" - "Opacity modifier — bg-primary-500/50, text-gray-900/80" - "Negative values — -m-4, -top-2, -translate-x-4" - "!important modifier — !p-4, !bg-white" - "Gradient support — bg-gradient-to-{r,l,t,b,tr,tl,br,bl} direction + from-/via-/to- color stops" - "Gradient position modifiers — from-10%, via-50%, to-90%" - "Gradient composes into backgroundImage: linear-gradient(...)" - "Flutter adapter maps gradient to FlutterGradient (recipe-only target)" - "Multi-layer shadow composition — shadow-* and ring-* merge into a single boxShadow string" - "Ring + shadow combined — ring layer always prepended before shadow layer (Tailwind convention)" - "!important propagation through shadow/ring composition" - "dark: variant — conditional dark mode via DotOptions" - "Responsive variants — sm:/md:/lg:/xl:/2xl: mobile-first cascade" - "Custom breakpoints — createDotConfig({ breakpoints: ['tablet', 'desktop'] })" - "State variants — dotMap() → { base, hover, focus, active, focus-visible, focus-within, disabled }" - "dotVariants() — CVA-style variant factory (base, variants, defaultVariants, compoundVariants)" - "dotCx() — clsx replacement for filtering falsy values and joining utility strings" - "Shared resolver pipeline — one resolver, target-specific adapters (adaptNative / adaptWeb / adaptFlutter)" - "adaptNative() — px→number, transform→array, boxShadow→RN shadow props, 45+ unsupported props silently dropped" - "RN native subpath — import from '@hua-labs/dot/native' (auto target: 'native')" - "RN conditional export — Metro resolves 'react-native' condition automatically" - "adaptFlutter() — CSSProperties → FlutterRecipe (structured widget composition map)" - "FlutterRecipe fields — decoration (BoxDecoration), padding/margin (EdgeInsets), constraints (SizedBox), layout (Row/Column), flexChild (Flexible/Expanded), positioning (Positioned), textStyle (TextStyle), transform (Matrix4), opacity, visible, aspectRatio, zIndex" - "FlutterGradient — bg-gradient-to-* + from/via/to stops → LinearGradient recipe" - "Flutter target: 'flutter' — dot('p-4', { target: 'flutter' }) → FlutterRecipe" - "dotExplain() — resolves styles + returns DotCapabilityReport (dropped, approximated, capabilities per property)" - "CAPABILITY_MATRIX — static map of utility family → target → support level (native/approximate/recipe-only/plugin-backed/unsupported)" - "PROPERTY_TO_FAMILY — static map of CSS property → utility family for capability lookup" - "getCapability(property, target, value?) — programmatic per-property capability query" - "createDotConfig() — token overrides (colors, spacing, borderRadius, fontSize, gridCols, breakpoints, remBase, etc.)" - "CSS variable bridge — 17 semantic color tokens (background, foreground, card, muted, accent, etc.)" - "strictMode — throws on unknown tokens; warnUnknown — dev console.warn" - "2-layer FIFO cache — input-level (500) + token-level (1000) caching" - "clearDotCache() — reset after config changes or for memory management" related_packages: - "@hua-labs/hua" - "@hua-labs/ui" - "@hua-labs/@hua-labs/dot-aot" compatibility: node: ">=20.0.0"