twirlwind 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danila Poyarkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# Twirlwind
+
+Tailwind v4-first CSS-to-utility-class serializer for JavaScript/TypeScript.
+
+Converts style objects, CSS declaration strings, and `CSSStyleDeclaration` values into clean Tailwind utility classes. Prefers canonical utilities, falls back to arbitrary values, then arbitrary properties — every CSS property produces valid output.
+
+## Install
+
+```sh
+npm install twirlwind
+```
+
+## Quick start
+
+```ts
+import { styleToClassName } 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"
+```
+
+## API
+
+### `styleToTailwind(input, options?)`
+
+Full conversion result with metadata.
+
+```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?)`
+
+Returns just the class string.
+
+```ts
+styleToClassName({ padding: '16px', color: 'white' })
+// → "p-4 text-white"
+```
+
+### `styleToClasses(input, options?)`
+
+Returns an array of class strings.
+
+```ts
+styleToClasses({ margin: '8px 16px' })
+// → ["my-2", "mx-4"]
+```
+
+### `cssTextToTailwind(cssText, options?)`
+
+Parses a CSS declaration string.
+
+```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')
+
+// CSSStyleDeclaration (browser)
+styleToClassName(element.style)
+
+// Iterable of [property, value] pairs
+styleToClassName(
+  new Map([
+    ['display', 'flex'],
+    ['padding', '16px']
+  ])
+)
+```
+
+## Features
+
+### Color matching
+
+Matches colors across formats to Tailwind's palette — OKLCH (v4), hex (v3), `rgb()`, keywords, and 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"
+```
+
+### Shorthand expansion
+
+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"
+```
+
+### Multi-value transforms and filters
+
+Compound `transform` and `filter` declarations decompose into individual utility classes.
+
+```ts
+styleToClassName({ transform: 'translateX(8px) rotate(45deg)' })
+// → "rotate-45 translate-x-2"
+
+styleToClassName({ filter: 'blur(8px) brightness(0.75)' })
+// → "blur brightness-75"
+```
+
+### Compression
+
+Expanded longhands compress to shorthand utilities when values match.
+
+```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"
+```
+
+### Variants
+
+Nested objects map to Tailwind variants — pseudo-classes, media queries, and container queries.
+
+```ts
+styleToClassName({
+  color: 'white',
+  ':hover': { color: '#3b82f6' },
+  '@media (min-width: 768px)': { display: 'grid' },
+  '@media (prefers-color-scheme: dark)': { backgroundColor: 'black' },
+  '@container (min-width: 512px)': { display: 'flex' }
+})
+// → "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.
+
+```ts
+styleToClassName({ scrollTimelineName: '--main' })
+// → "[scroll-timeline-name:--main]"
+
+styleToClassName({ width: '37px' })
+// → "w-[37px]"
+```
+
+## Options
+
+```ts
+styleToTailwind(input, {
+  // Allow arbitrary value utilities like w-[37px]
+  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' }
+  }
+})
+```
+
+## How it works
+
+1. **Normalize** — camelCase → kebab-case, numeric → px, vendor prefixes, `!important`
+2. **Expand shorthands** — `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
+5. **Sort** — deterministic output ordering
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,58 @@
+//#region src/types.d.ts
+type StylePrimitive = string | number | null | undefined;
+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 = {
+  spacing?: Record<string, string>;
+  colors?: Record<string, string>;
+};
+type StyleToTailwindOptions = {
+  mode?: ConversionMode;
+  tailwindVersion?: '4';
+  theme?: TwirlwindTheme;
+  allowArbitraryValues?: boolean;
+  allowArbitraryProperties?: boolean;
+  preferThemeTokens?: boolean;
+  compression?: CompressionMode;
+  sort?: SortMode;
+  important?: boolean;
+  colorMatch?: ColorMatchMode;
+  numericMultipliers?: NumericMultiplierMode;
+};
+type CssDeclaration = {
+  property: string;
+  value: string;
+  important: boolean;
+  variants: string[];
+};
+type ConvertedDeclaration = CssDeclaration & {
+  className: string;
+  kind: 'exact' | 'arbitrary';
+};
+type ConversionWarning = {
+  declaration: CssDeclaration;
+  message: string;
+};
+type StyleToTailwindResult = {
+  className: string;
+  classes: string[];
+  exact: ConvertedDeclaration[];
+  arbitrary: ConvertedDeclaration[];
+  unmatched: CssDeclaration[];
+  warnings: ConversionWarning[];
+};
+//#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;
+//#endregion
+export { type ConvertedDeclaration, type CssDeclaration, type StyleInput, type StyleObject, type StylePrimitive, type StyleToTailwindOptions, type StyleToTailwindResult, type TwirlwindTheme, cssTextToTailwind, styleToClassName, styleToClasses, styleToTailwind };