twirlwind 0.1.0 → 0.2.0

package/README.md

@@ -10,100 +10,58 @@ Converts style objects, CSS declaration strings, and `CSSStyleDeclaration` value
 npm install twirlwind
 ```
 
-## Quick start
+## Usage
 
 ```ts
-import { styleToClassName } from 'twirlwind'
+import { twirl } from 'twirlwind'
 
-styleToClassName({
-  display: 'flex',
-  justifyContent: 'center',
-  padding: '16px 8px',
-  backgroundColor: 'oklch(62.3% 0.214 259.815)'
-})
-// → "flex py-4 px-2 justify-center bg-blue-500"
+twirl({ display: 'flex', padding: '16px 8px', color: '#ef4444' })
+// → "flex py-4 px-2 text-red-500"
 ```
 
-## API
-
-### `styleToTailwind(input, options?)`
+### Inputs
 
-Full conversion result with metadata.
+`twirl()` accepts any of these and returns a class string:
 
 ```ts
-import { styleToTailwind } from 'twirlwind'
-
-const result = styleToTailwind({ display: 'flex', width: '37px' })
-
-result.className // "flex w-[37px]"
-result.classes // ["flex", "w-[37px]"]
-result.exact // ConvertedDeclaration[] — exact utility matches
-result.arbitrary // ConvertedDeclaration[] — arbitrary value/property fallbacks
-result.unmatched // CssDeclaration[] — declarations that couldn't be converted
-result.warnings // ConversionWarning[]
-```
-
-### `styleToClassName(input, options?)`
+// Style object
+twirl({ backgroundColor: 'white', fontSize: '16px' })
 
-Returns just the class string.
+// CSS string
+twirl('display: flex; padding: 16px')
 
-```ts
-styleToClassName({ padding: '16px', color: 'white' })
-// → "p-4 text-white"
-```
-
-### `styleToClasses(input, options?)`
-
-Returns an array of class strings.
+// CSSStyleDeclaration (browser)
+twirl(element.style)
 
-```ts
-styleToClasses({ margin: '8px 16px' })
-// → ["my-2", "mx-4"]
+// Computed styles
+twirl(getComputedStyle(element))
 ```
 
-### `cssTextToTailwind(cssText, options?)`
+### Detailed result
 
-Parses a CSS declaration string.
+Use `twirl.convert()` when you need metadata:
 
 ```ts
-cssTextToTailwind('display: flex; gap: 16px; padding: 8px')
-// → { className: "flex p-2 gap-4", ... }
-```
-
-## Input formats
-
-```ts
-// Style object (camelCase or kebab-case)
-styleToClassName({ backgroundColor: 'white', 'font-size': '16px' })
-
-// CSS declaration string
-styleToClassName('display: flex; padding: 16px')
+const result = twirl.convert({ display: 'flex', width: '37px' })
 
-// CSSStyleDeclaration (browser)
-styleToClassName(element.style)
-
-// Iterable of [property, value] pairs
-styleToClassName(
-  new Map([
-    ['display', 'flex'],
-    ['padding', '16px']
-  ])
-)
+result.className // "flex w-[37px]"
+result.classes // ["flex", "w-[37px]"]
+result.exact // exact utility matches
+result.arbitrary // arbitrary value/property fallbacks
+result.unmatched // declarations that couldn't be converted
 ```
 
 ## Features
 
 ### Color matching
 
-Matches colors across formats to Tailwind's palette — OKLCH (v4), hex (v3), `rgb()`, keywords, and opacity modifiers.
+Matches across formats — OKLCH, hex, `rgb()`, keywords, opacity modifiers.
 
 ```ts
-styleToClassName({ color: '#ef4444' }) // "text-red-500"
-styleToClassName({ color: 'rgb(59 130 246)' }) // "text-blue-500"
-styleToClassName({ color: 'oklch(62.3% 0.214 259.815)' }) // "text-blue-500"
-styleToClassName({ color: 'oklch(62.3% 0.214 259.815 / 50%)' }) // "text-blue-500/50"
-styleToClassName({ color: 'inherit' }) // "text-inherit"
-styleToClassName({ color: 'currentColor' }) // "text-current"
+twirl({ color: '#ef4444' }) // "text-red-500"
+twirl({ color: 'rgb(59 130 246)' }) // "text-blue-500"
+twirl({ color: 'oklch(62.3% 0.214 259.815 / 50%)' }) // "text-blue-500/50"
+twirl({ color: 'currentColor' }) // "text-current"
 ```
 
 ### Shorthand expansion
@@ -111,49 +69,39 @@ styleToClassName({ color: 'currentColor' }) // "text-current"
 CSS shorthands decompose into Tailwind longhands.
 
 ```ts
-styleToClassName({ border: '2px solid #ef4444' })
-// → "border-2 border-red-500 border-solid"
-
-styleToClassName({ font: 'bold 16px/1.5 sans-serif' })
-// → "font-bold text-base leading-normal font-sans"
-
-styleToClassName({ background: 'white center no-repeat' })
-// → "bg-white bg-center bg-no-repeat"
-
-styleToClassName({ transition: 'all 200ms ease-in' })
-// → "transition-all duration-200 ease-in"
+twirl({ border: '2px solid #ef4444' }) // "border-2 border-red-500 border-solid"
+twirl({ font: 'bold 16px/1.5 sans-serif' }) // "font-bold text-base leading-normal font-sans"
+twirl({ background: 'white center no-repeat' }) // "bg-white bg-center bg-no-repeat"
 ```
 
-### Multi-value transforms and filters
+### Multi-value parsing
 
-Compound `transform` and `filter` declarations decompose into individual utility classes.
+Compound `transform` and `filter` declarations decompose into individual classes.
 
 ```ts
-styleToClassName({ transform: 'translateX(8px) rotate(45deg)' })
-// → "rotate-45 translate-x-2"
-
-styleToClassName({ filter: 'blur(8px) brightness(0.75)' })
-// → "blur brightness-75"
+twirl({ transform: 'translateX(8px) rotate(45deg)' }) // "rotate-45 translate-x-2"
+twirl({ filter: 'blur(8px) brightness(0.75)' }) // "blur brightness-75"
+twirl({ scrollSnapType: 'x mandatory' }) // "snap-x snap-mandatory"
 ```
 
 ### Compression
 
-Expanded longhands compress to shorthand utilities when values match.
+Expanded longhands compress to shorthand utilities.
 
 ```ts
-styleToClassName({ margin: '8px' }) // "m-2" (not "mt-2 mr-2 mb-2 ml-2")
-styleToClassName({ inset: '0' }) // "inset-0"
-styleToClassName({ padding: '8px 16px' }) // "py-2 px-4"
-styleToClassName({ borderRadius: '8px' }) // "rounded-lg"
-styleToClassName({ gap: '12px 12px' }) // "gap-3"
+twirl({ margin: '8px' }) // "m-2"
+twirl({ inset: '0' }) // "inset-0"
+twirl({ padding: '8px 16px' }) // "py-2 px-4"
+twirl({ borderRadius: '8px' }) // "rounded-lg"
+twirl({ gap: '12px 12px' }) // "gap-3"
 ```
 
 ### Variants
 
-Nested objects map to Tailwind variants — pseudo-classes, media queries, and container queries.
+Nested objects map to Tailwind variants.
 
 ```ts
-styleToClassName({
+twirl({
   color: 'white',
   ':hover': { color: '#3b82f6' },
   '@media (min-width: 768px)': { display: 'grid' },
@@ -163,48 +111,25 @@ styleToClassName({
 // → "text-white hover:text-blue-500 md:grid dark:bg-black @lg:flex"
 ```
 
-### Scroll snap decomposition
-
-```ts
-styleToClassName({ scrollSnapType: 'x mandatory' })
-// → "snap-x snap-mandatory"
-```
-
 ### Arbitrary fallback
 
-Every CSS property produces valid output. Unknown properties use `[property:value]` syntax.
+Every CSS property produces valid output.
 
 ```ts
-styleToClassName({ scrollTimelineName: '--main' })
-// → "[scroll-timeline-name:--main]"
-
-styleToClassName({ width: '37px' })
-// → "w-[37px]"
+twirl({ scrollTimelineName: '--main' }) // "[scroll-timeline-name:--main]"
+twirl({ width: '37px' }) // "w-[37px]"
 ```
 
 ## Options
 
 ```ts
-styleToTailwind(input, {
-  // Allow arbitrary value utilities like w-[37px]
+twirl(input, {
   allowArbitraryValues: true, // default: true
-
-  // Allow arbitrary property fallbacks like [scroll-timeline-name:--x]
   allowArbitraryProperties: true, // default: true
-
-  // Compress matching longhands to shorthands
   compression: 'safe', // "none" | "safe" | "aggressive"
-
-  // Sort output classes
   sort: 'grouped', // "input" | "tailwind" | "grouped"
-
-  // Color matching strategy
   colorMatch: 'exact', // "exact" | "nearest" | "none"
-
-  // Spacing token multiplier mode
   numericMultipliers: 'integer', // "all" | "integer" | "never"
-
-  // Custom theme colors/spacing
   theme: {
     colors: { brand: '#ff6600' },
     spacing: { '18': '4.5rem' }
@@ -215,9 +140,9 @@ styleToTailwind(input, {
 ## How it works
 
 1. **Normalize** — camelCase → kebab-case, numeric → px, vendor prefixes, `!important`
-2. **Expand shorthands** — `margin`, `border`, `font`, `background`, `transition`, `overflow`, `gap`, etc.
+2. **Expand** — `margin`, `border`, `font`, `background`, `transition`, `overflow`, `gap`, etc.
 3. **Convert** — exact utility → value alias → spacing token → color match → arbitrary value → arbitrary property
-4. **Compress** — merge matching longhands back to axis/all shorthand utilities
+4. **Compress** — merge longhands back to shorthand utilities
 5. **Sort** — deterministic output ordering
 
 ## License

package/dist/index.d.mts

@@ -4,55 +4,42 @@ interface StyleObject {
   [property: string]: StylePrimitive | StyleObject;
 }
 type StyleInput = string | StyleObject | CSSStyleDeclaration | Iterable<[string, StylePrimitive]>;
-type ConversionMode = 'pretty' | 'lossless' | 'strict';
-type SortMode = 'input' | 'tailwind' | 'grouped';
-type CompressionMode = 'none' | 'safe' | 'aggressive';
-type ColorMatchMode = 'exact' | 'nearest' | 'none';
-type NumericMultiplierMode = 'all' | 'integer' | 'never';
-type TwirlwindTheme = {
+type Theme = {
   spacing?: Record<string, string>;
   colors?: Record<string, string>;
 };
-type StyleToTailwindOptions = {
-  mode?: ConversionMode;
-  tailwindVersion?: '4';
-  theme?: TwirlwindTheme;
+type Options = {
+  theme?: Theme;
   allowArbitraryValues?: boolean;
   allowArbitraryProperties?: boolean;
-  preferThemeTokens?: boolean;
-  compression?: CompressionMode;
-  sort?: SortMode;
+  compression?: 'none' | 'safe' | 'aggressive';
+  sort?: 'input' | 'tailwind' | 'grouped';
   important?: boolean;
-  colorMatch?: ColorMatchMode;
-  numericMultipliers?: NumericMultiplierMode;
+  colorMatch?: 'exact' | 'nearest' | 'none';
+  numericMultipliers?: 'all' | 'integer' | 'never';
 };
-type CssDeclaration = {
+type Declaration = {
   property: string;
   value: string;
   important: boolean;
   variants: string[];
 };
-type ConvertedDeclaration = CssDeclaration & {
+type ConvertedDeclaration = Declaration & {
   className: string;
   kind: 'exact' | 'arbitrary';
 };
-type ConversionWarning = {
-  declaration: CssDeclaration;
-  message: string;
-};
-type StyleToTailwindResult = {
+type Result = {
   className: string;
   classes: string[];
   exact: ConvertedDeclaration[];
   arbitrary: ConvertedDeclaration[];
-  unmatched: CssDeclaration[];
-  warnings: ConversionWarning[];
+  unmatched: Declaration[];
 };
 //#endregion
 //#region src/index.d.ts
-declare function styleToTailwind(input: StyleInput, options?: StyleToTailwindOptions): StyleToTailwindResult;
-declare function styleToClassName(input: StyleInput, options?: StyleToTailwindOptions): string;
-declare function styleToClasses(input: StyleInput, options?: StyleToTailwindOptions): string[];
-declare function cssTextToTailwind(cssText: string, options?: StyleToTailwindOptions): StyleToTailwindResult;
+declare function twirl(input: StyleInput, options?: Options): string;
+declare namespace twirl {
+  var convert: (input: StyleInput, options?: Options) => Result;
+}
 //#endregion
-export { type ConvertedDeclaration, type CssDeclaration, type StyleInput, type StyleObject, type StylePrimitive, type StyleToTailwindOptions, type StyleToTailwindResult, type TwirlwindTheme, cssTextToTailwind, styleToClassName, styleToClasses, styleToTailwind };
+export { type ConvertedDeclaration, type Declaration, type Options, type Result, type StyleInput, type StyleObject, type StylePrimitive, type Theme, twirl };

package/dist/index.mjs

@@ -3482,8 +3482,6 @@ const defaultTheme = {
 };
 function resolveOptions(options = {}) {
 	return {
-		mode: options.mode ?? "pretty",
-		tailwindVersion: "4",
 		theme: {
 			spacing: {
 				...defaultTheme.spacing,
@@ -3496,7 +3494,6 @@ function resolveOptions(options = {}) {
 		},
 		allowArbitraryValues: options.allowArbitraryValues ?? true,
 		allowArbitraryProperties: options.allowArbitraryProperties ?? true,
-		preferThemeTokens: options.preferThemeTokens ?? true,
 		compression: options.compression ?? "safe",
 		sort: options.sort ?? "grouped",
 		important: options.important ?? false,
@@ -3506,40 +3503,27 @@ function resolveOptions(options = {}) {
 }
 //#endregion
 //#region src/index.ts
-function styleToTailwind(input, options) {
-	const resolvedOptions = resolveOptions(options);
-	const conversionPairs = expandShorthands(normalizeInput(input)).map((declaration) => ({
+function convert(input, options) {
+	const resolved = resolveOptions(options);
+	const pairs = expandShorthands(normalizeInput(input)).map((declaration) => ({
 		declaration,
-		converted: convertDeclaration(declaration, resolvedOptions)
+		converted: convertDeclaration(declaration, resolved)
 	}));
-	const convertedDeclarations = sortConverted(compressConverted(conversionPairs.flatMap(({ converted }) => {
+	const sorted = sortConverted(compressConverted(pairs.flatMap(({ converted }) => {
 		if (!converted) return [];
 		return Array.isArray(converted) ? converted : [converted];
-	}), resolvedOptions), resolvedOptions);
-	const exact = convertedDeclarations.filter((converted) => converted.kind === "exact");
-	const arbitrary = convertedDeclarations.filter((converted) => converted.kind === "arbitrary");
-	const unmatched = conversionPairs.flatMap(({ declaration, converted }) => converted ? [] : [declaration]);
-	const classes = convertedDeclarations.map(({ className }) => className);
+	}), resolved), resolved);
 	return {
-		className: classes.join(" "),
-		classes,
-		exact,
-		arbitrary,
-		unmatched,
-		warnings: unmatched.map((declaration) => ({
-			declaration,
-			message: "No Tailwind utility or fallback could be emitted."
-		}))
+		className: sorted.map(({ className }) => className).join(" "),
+		classes: sorted.map(({ className }) => className),
+		exact: sorted.filter((c) => c.kind === "exact"),
+		arbitrary: sorted.filter((c) => c.kind === "arbitrary"),
+		unmatched: pairs.flatMap(({ declaration, converted }) => converted ? [] : [declaration])
 	};
 }
-function styleToClassName(input, options) {
-	return styleToTailwind(input, options).className;
-}
-function styleToClasses(input, options) {
-	return styleToTailwind(input, options).classes;
-}
-function cssTextToTailwind(cssText, options) {
-	return styleToTailwind(cssText, options);
+function twirl(input, options) {
+	return convert(input, options).className;
 }
+twirl.convert = convert;
 //#endregion
-export { cssTextToTailwind, styleToClassName, styleToClasses, styleToTailwind };
+export { twirl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twirlwind",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tailwind v4-first CSS style object to utility class serializer with lossless arbitrary-property fallback.",
   "keywords": [
     "converter",