rnwind 0.0.1 → 0.0.3

package/src/core/parser/color.ts

@@ -0,0 +1,191 @@
+import type { CssColor, LABColor } from 'lightningcss'
+import { formatHex, rgb as culoriRgb } from 'culori'
+
+/**
+ * Clamp a 0-255 float to the integer byte range RN color strings accept.
+ * @param value Unclamped float (may be negative or above 255).
+ * @returns Integer in `[0, 255]`.
+ */
+function clampByte(value: number): number {
+  if (value < 0) return 0
+  if (value > 255) return 255
+  return Math.round(value)
+}
+
+/**
+ * Two-digit hex encoding of a 0-255 byte.
+ * @param byte Byte value (may be out-of-range — clamped).
+ * @returns Zero-padded two-char hex string.
+ */
+function byteToHex(byte: number): string {
+  const hex = clampByte(byte).toString(16)
+  return hex.length === 1 ? `0${hex}` : hex
+}
+
+/**
+ * Format an integer-RGB triple + alpha as `#rrggbb` or `rgba(r, g, b, a)`.
+ * @param r 0-255 red.
+ * @param g 0-255 green.
+ * @param b 0-255 blue.
+ * @param alpha 0-1 alpha.
+ * @returns Color string.
+ */
+function rgbIntsToString(r: number, g: number, b: number, alpha: number): string {
+  if (alpha >= 1) return `#${byteToHex(r)}${byteToHex(g)}${byteToHex(b)}`
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`
+}
+
+/**
+ * Format a float-RGB triple + alpha (CSS `color(srgb …)` forms) as
+ * hex/rgba.
+ * @param r 0-1 red.
+ * @param g 0-1 green.
+ * @param b 0-1 blue.
+ * @param alpha 0-1 alpha.
+ * @returns Color string.
+ */
+function floatRgbToString(r: number, g: number, b: number, alpha: number): string {
+  return rgbIntsToString(clampByte(r * 255), clampByte(g * 255), clampByte(b * 255), alpha)
+}
+
+/**
+ * Dispatch a LAB-family color through culori's hex formatter.
+ * @param color Typed LAB-family color.
+ * @returns `#rrggbb` string, or `null` when culori couldn't convert.
+ */
+function culoriHexFor(color: LABColor): string | null {
+  switch (color.type) {
+    case 'oklch': {
+      return formatHex({ mode: 'oklch', l: color.l, c: color.c, h: color.h }) ?? null
+    }
+    case 'oklab': {
+      return formatHex({ mode: 'oklab', l: color.l, a: color.a, b: color.b }) ?? null
+    }
+    case 'lab': {
+      return formatHex({ mode: 'lab', l: color.l, a: color.a, b: color.b }) ?? null
+    }
+    case 'lch': {
+      return formatHex({ mode: 'lch', l: color.l, c: color.c, h: color.h }) ?? null
+    }
+    default: {
+      return null
+    }
+  }
+}
+
+/**
+ * Composite a culori-produced sRGB hex with the source alpha into the RN
+ * color string. Shared tail for every culori-backed conversion (lab
+ * family, XYZ, wide-gamut RGB): opaque → the hex as-is; translucent →
+ * `rgba(...)` rebuilt from the hex channels.
+ * @param hex sRGB hex from culori, or `null` when culori rejected the color.
+ * @param alpha Source alpha (0–1).
+ * @returns RN color string.
+ */
+function withAlpha(hex: string | null, alpha: number): string {
+  if (!hex) return alpha < 1 ? 'rgba(0, 0, 0, 0)' : 'transparent'
+  if (alpha >= 1) return hex
+  const back = culoriRgb(hex)
+  if (!back) return hex
+  return rgbIntsToString(clampByte(back.r * 255), clampByte(back.g * 255), clampByte(back.b * 255), alpha)
+}
+
+/**
+ * Convert a LAB / LCH / OKLAB / OKLCH color to sRGB hex via culori. RN
+ * can't evaluate these modern color spaces at paint time; compile-time
+ * lowering to sRGB is the only portable path.
+ * @param color Typed lab-family color.
+ * @returns Hex or rgba string in sRGB.
+ */
+function labFamilyToHex(color: LABColor): string {
+  return withAlpha(culoriHexFor(color), color.alpha)
+}
+
+/**
+ * Convert a wide-gamut `color(<space> r g b)` triple to sRGB hex via
+ * culori. The channels are NOT sRGB — each space (display-p3, rec2020,
+ * a98-rgb, prophoto-rgb, srgb-linear) carries its own primaries / transfer
+ * function, so a bare `channel * 255` would mis-paint. culori does the
+ * gamut + gamma conversion to sRGB.
+ * @param mode culori mode key for the source space.
+ * @param r Source red (0–1).
+ * @param g Source green (0–1).
+ * @param b Source blue (0–1).
+ * @param alpha Alpha channel (0–1).
+ * @returns sRGB color string RN accepts.
+ */
+function wideGamutToHex(mode: 'lrgb' | 'p3' | 'a98' | 'prophoto' | 'rec2020', r: number, g: number, b: number, alpha: number): string {
+  return withAlpha(formatHex({ mode, r, g, b }) ?? null, alpha)
+}
+
+/**
+ * Convert a CSS `color(xyz-d50 …)` / `color(xyz-d65 …)` value to sRGB hex
+ * via culori.
+ * @param color Typed XYZ color (discriminated by `type`).
+ * @param color.type Whether the color is in the D50 or D65 XYZ space.
+ * @param color.x CIE X component (0–1).
+ * @param color.y CIE Y component (0–1).
+ * @param color.z CIE Z component (0–1).
+ * @param color.alpha Alpha channel (0–1).
+ * @returns `#rrggbb` string, or `'transparent'` when culori rejects it.
+ */
+function xyzToHex(color: { type: 'xyz-d50' | 'xyz-d65'; x: number; y: number; z: number; alpha: number }): string {
+  const mode = color.type === 'xyz-d50' ? 'xyz50' : 'xyz65'
+  return withAlpha(formatHex({ mode, x: color.x, y: color.y, z: color.z }) ?? null, color.alpha)
+}
+
+/**
+ * Convert a lightningcss `CssColor` to an RN-safe color string. RGB
+ * passes through unchanged. LAB / LCH / OKLAB / OKLCH / `color(xyz-…)`
+ * forms go through culori to reach sRGB — RN's native view manager only
+ * understands sRGB-family strings. SystemColor keywords (`'background'`,
+ * `'canvas'`, …) pass through untouched; they have no RN analog and the
+ * runtime ignores unknown color strings gracefully.
+ * @param color Typed color value.
+ * @returns Color string RN accepts.
+ */
+export function cssColorToString(color: CssColor): string {
+  if (typeof color === 'string') return color
+  switch (color.type) {
+    case 'rgb': {
+      return rgbIntsToString(color.r, color.g, color.b, color.alpha)
+    }
+    case 'lab':
+    case 'lch':
+    case 'oklab':
+    case 'oklch': {
+      return labFamilyToHex(color)
+    }
+    case 'srgb': {
+      return floatRgbToString(color.r, color.g, color.b, color.alpha)
+    }
+    case 'srgb-linear': {
+      return wideGamutToHex('lrgb', color.r, color.g, color.b, color.alpha)
+    }
+    case 'display-p3': {
+      return wideGamutToHex('p3', color.r, color.g, color.b, color.alpha)
+    }
+    case 'a98-rgb': {
+      return wideGamutToHex('a98', color.r, color.g, color.b, color.alpha)
+    }
+    case 'prophoto-rgb': {
+      return wideGamutToHex('prophoto', color.r, color.g, color.b, color.alpha)
+    }
+    case 'rec2020': {
+      return wideGamutToHex('rec2020', color.r, color.g, color.b, color.alpha)
+    }
+    case 'xyz-d50':
+    case 'xyz-d65': {
+      return xyzToHex(color)
+    }
+    case 'currentcolor': {
+      return 'currentColor'
+    }
+    case 'light-dark': {
+      return cssColorToString(color.light)
+    }
+    default: {
+      return 'transparent'
+    }
+  }
+}

package/src/core/parser/constants.ts

@@ -0,0 +1,11 @@
+/** 1 rem = 16 px — matches the CSS default so unit-bare Tailwind spacing stays predictable. */
+export const REM_TO_PX = 16
+
+// Hot-path regexes hoisted to module scope so they're compiled once per
+// process; an inline literal would recompile on every declaration.
+export const BARE_NUMBER_REGEX = /^-?\d+(?:\.\d+)?$/
+export const LENGTH_PX_REGEX = /^(-?\d+(?:\.\d+)?)px$/
+export const LENGTH_REM_REGEX = /^(-?\d+(?:\.\d+)?)rem$/
+export const CALC_RATIO_REGEX = /^calc\(\s*(-?\d+(?:\.\d+)?)\s*\/\s*(-?\d+(?:\.\d+)?)\s*\)$/
+export const CALC_MUL_REGEX = /^calc\(\s*(-?\d+(?:\.\d+)?)(?:px|rem)?\s*\*\s*(-?\d+(?:\.\d+)?)\s*\)$/
+export const KEBAB_BOUNDARY_REGEX = /-([a-z])/g

package/src/core/parser/declaration.ts

@@ -0,0 +1,340 @@
+/* eslint-disable sonarjs/cognitive-complexity -- the main Declaration → RN-entries dispatcher is intentionally a flat switch so each branch keeps its narrowed value type */
+import type { Declaration as LcDeclaration, TokenOrValue } from 'lightningcss'
+import { kebabToCamel } from './case-convert'
+import { cssColorToString } from './color'
+import { dimensionPercentageToNumber, gapValueToValue, lengthPercentageOrAutoToValue, sizeLikeToValue } from './length'
+import {
+  expandBorderColor,
+  expandBorderRadius,
+  expandFourSided,
+  expandGap,
+  expandLogicalBlock,
+  expandLogicalInline,
+  flexToEntries,
+} from './shorthand'
+import { coerceUnparsedValue, serializeTokens, substituteThemeVars } from './tokens'
+import { displayToEntries, fontSizeToPx, fontWeightToValue, zIndexToNumber } from './typography'
+import { dispatchMotionDeclaration } from './motion-dispatcher'
+import { dispatchTypographyDeclaration } from './typography-dispatcher'
+import { dispatchLayoutDeclaration } from './layout-dispatcher'
+import { dispatchColorPropertyDeclaration } from './color-properties-dispatcher'
+import { dispatchBorderDeclaration } from './border-dispatcher'
+import { detectSafeAreaMarker } from './safe-area'
+import type { RNEntry } from './types'
+
+/** CSS timing-function properties that need `cubic-bezier(...)` snapping. */
+const TIMING_FUNCTION_PROPS = new Set(['transition-timing-function', 'animation-timing-function'])
+
+/** CSS easing keywords Reanimated v4's CSS engine accepts as strings. */
+const CSS_EASING_KEYWORDS = new Set(['linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out', 'step-start', 'step-end'])
+
+/** CSS properties with no useful RN equivalent — silently dropped. */
+const UNSUPPORTED_LOGICAL_PROPS = new Set([
+  'border-inline-style',
+  'border-block-style',
+  'border-inline-start-style',
+  'border-inline-end-style',
+  'border-block-start-style',
+  'border-block-end-style',
+])
+
+/**
+ * Pick the closest predefined CSS easing keyword for a `cubic-bezier`
+ * control-point set. Mirrors {@link snapCubicBezierToKeyword} in
+ * `animation.ts` — kept here so the unparsed-string path doesn't need
+ * to import a typed-only helper.
+ * @param x1 First control-point x (0–1).
+ * @param y1 First control-point y (0–1).
+ * @param x2 Second control-point x (0–1).
+ * @param y2 Second control-point y (0–1).
+ * @returns CSS easing keyword.
+ */
+function snapBezier(x1: number, y1: number, x2: number, y2: number): string {
+  const tol = 0.01
+  const eq = (a: number, b: number): boolean => Math.abs(a - b) < tol
+  if (eq(x1, 0) && eq(y1, 0) && eq(x2, 1) && eq(y2, 1)) return 'linear'
+  if (eq(x1, 0.25) && eq(y1, 0.1) && eq(x2, 0.25) && eq(y2, 1)) return 'ease'
+  if (eq(x1, 0.4) && eq(y1, 0) && eq(x2, 1) && eq(y2, 1)) return 'ease-in'
+  if (eq(x1, 0) && eq(y1, 0) && eq(x2, 0.2) && eq(y2, 1)) return 'ease-out'
+  if (eq(x1, 0.4) && eq(y1, 0) && eq(x2, 0.2) && eq(y2, 1)) return 'ease-in-out'
+  const startsFlat = x1 < 0.1
+  const endsFlat = x2 > 0.9
+  if (startsFlat && !endsFlat) return 'ease-out'
+  if (!startsFlat && endsFlat) return 'ease-in'
+  return 'ease-in-out'
+}
+
+/**
+ * Snap a cubic-bezier expression string to the closest CSS keyword
+ * Reanimated v4's CSS engine accepts. Strings that already are keywords
+ * pass through unchanged.
+ * @param value Resolved value text from an unparsed timing-function declaration.
+ * @returns CSS easing keyword.
+ */
+function coerceCubicBezierString(value: string): string {
+  const text = value.trim()
+  if (CSS_EASING_KEYWORDS.has(text)) return text
+  const match = /^cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)$/.exec(text)
+  if (!match) return 'ease-in-out'
+  const [, x1, y1, x2, y2] = match
+  return snapBezier(Number(x1), Number(y1), Number(x2), Number(y2))
+}
+
+/**
+ * Fast-path check for the handful of color property names Tailwind emits.
+ * @param property Kebab-case CSS property name.
+ * @returns Whether the property's value should be treated as a color.
+ */
+function isColorProperty(property: string): boolean {
+  return (
+    property === 'color' ||
+    property === 'background-color' ||
+    (property.startsWith('border-') && property.endsWith('-color')) ||
+    property.endsWith('-color')
+  )
+}
+
+/**
+ * Convert an unparsed declaration (typical Tailwind v4 output containing
+ * `var()` / `calc()`) into RN entries. Serializes the token list, then
+ * coerces the flat string into a number / keyword / length via a tight
+ * set of shapes Tailwind actually emits.
+ * @param property Real property name (kebab-case).
+ * @param tokens Token list from lightningcss.
+ * @param themeVars Optional lookup table for resolving `var(--x)` references.
+ * @returns RN entries — usually one, empty when unusable.
+ */
+function unparsedToEntries(
+  property: string,
+  tokens: readonly TokenOrValue[],
+  themeVars: ReadonlyMap<string, string> | undefined,
+): readonly RNEntry[] {
+  if (property.length === 0) return []
+  // Safe-area detection runs BEFORE token serialization because
+  // `env()` serializes to an empty string, which would strip the side
+  // info we need. If the tokens encode a recognised `env(safe-area-inset-*)`
+  // pattern (pure / `max(..., n)` / `calc(...+n)` / `h-screen-safe`),
+  // emit a runtime-resolved marker instead.
+  if (UNSUPPORTED_LOGICAL_PROPS.has(property)) return []
+  const safe = detectSafeAreaMarker(tokens, themeVars)
+  if (safe !== null) return [[kebabToCamel(property), safe]]
+  let text = serializeTokens(tokens)
+  if (themeVars && themeVars.size > 0) text = substituteThemeVars(text, themeVars)
+  const coerced = coerceUnparsedValue(text)
+  if (coerced === null) return []
+  // Skip values that didn't resolve past their `var()` wrapper — they
+  // came from a `@property --tw-*` token without a real fallback.
+  // Tailwind v4's `border-N` emits `border-style: var(--tw-border-style)`
+  // expecting the cascade to fill it in; in RN we drop them and rely on
+  // RN's default (solid).
+  if (typeof coerced === 'string' && coerced.startsWith('var(')) return []
+  // Logical-direction CSS properties RN doesn't have direct equivalents
+  // for. Keep the dropped names in one place so it's easy to audit.
+  if (UNSUPPORTED_LOGICAL_PROPS.has(property)) return []
+  if (TIMING_FUNCTION_PROPS.has(property) && typeof coerced === 'string') {
+    // `transition-colors` and similar emit `var(--tw-ease, cubic-bezier(...))`
+    // which serializes to a cubic-bezier STRING after substitution.
+    // Reanimated v4's CSS engine rejects those — snap to the closest
+    // predefined keyword (same logic as the typed `EasingFunction` path).
+    return [[kebabToCamel(property), coerceCubicBezierString(coerced)]]
+  }
+  if (isColorProperty(property) && typeof coerced === 'string') {
+    // Resolved user-theme color strings (e.g. `#ff0099`) go straight to
+    // the RN style — no further conversion needed.
+    return [[kebabToCamel(property), coerced]]
+  }
+  return [[kebabToCamel(property), coerced]]
+}
+
+/**
+ * Convert one lightningcss `Declaration` into zero-or-more RN style
+ * entries. Shorthand declarations (padding/margin/border-radius/flex) can
+ * emit multiple entries; skipped or unsupported properties emit none.
+ *
+ * The switch branches on `decl.property` so TypeScript narrows
+ * `decl.value` to the exact typed shape for each branch — no casts
+ * required. Unknown properties fall through to `[]`.
+ * @param decl One declaration from a lightningcss style rule.
+ * @param themeVars Optional lookup table for resolving `var(--x)` references inside unparsed values.
+ * @returns Array of `[key, value]` entries.
+ */
+export function declarationToRnEntries(decl: LcDeclaration, themeVars?: ReadonlyMap<string, string>): readonly RNEntry[] {
+  switch (decl.property) {
+    case 'custom': {
+      // Lightningcss routes two shapes through `custom`:
+      //  - Actual CSS custom properties (`--my-var`): no RN meaning, drop.
+      //  - Real properties it doesn't have a dedicated typed entry for
+      //    (e.g. `object-fit`, `pointer-events`, future CSS keyword-only
+      //    props): treat like an unparsed declaration so the keyword
+      //    surfaces in the RN style.
+      const customName = decl.value.name
+      if (customName.startsWith('--')) return []
+      return unparsedToEntries(customName, decl.value.value ?? [], themeVars)
+    }
+    case 'unparsed': {
+      return unparsedToEntries(decl.value.propertyId.property, decl.value.value, themeVars)
+    }
+    case 'color':
+    case 'background-color':
+    case 'border-top-color':
+    case 'border-right-color':
+    case 'border-bottom-color':
+    case 'border-left-color': {
+      // `background-color` narrows to `CssColor | 'background'` — the
+      // literal keyword means UA default. Skip the keyword.
+      if (typeof decl.value === 'string') return []
+      return [[kebabToCamel(decl.property), cssColorToString(decl.value)]]
+    }
+    case 'border-color': {
+      return expandBorderColor(decl.value)
+    }
+    case 'opacity': {
+      // Lightningcss hands us an `f32` for opacity, so values like `0.8`
+      // round-trip as `0.800000011920929`. Snap to 4 decimals to match the
+      // rest of the parser's numeric convention.
+      return [[decl.property, Math.round(decl.value * 10_000) / 10_000]]
+    }
+    case 'z-index': {
+      return [['zIndex', zIndexToNumber(decl.value)]]
+    }
+    case 'top':
+    case 'right':
+    case 'bottom':
+    case 'left': {
+      const v = lengthPercentageOrAutoToValue(decl.value)
+      if (v === null) return []
+      return [[decl.property, v]]
+    }
+    case 'inset': {
+      const top = lengthPercentageOrAutoToValue(decl.value.top)
+      const right = lengthPercentageOrAutoToValue(decl.value.right)
+      const bottom = lengthPercentageOrAutoToValue(decl.value.bottom)
+      const left = lengthPercentageOrAutoToValue(decl.value.left)
+      if (top === null || right === null || bottom === null || left === null) return []
+      return [
+        ['top', top],
+        ['right', right],
+        ['bottom', bottom],
+        ['left', left],
+      ]
+    }
+    case 'inset-inline': {
+      const start = lengthPercentageOrAutoToValue(decl.value.inlineStart)
+      const end = lengthPercentageOrAutoToValue(decl.value.inlineEnd)
+      if (start === null || end === null) return []
+      return [
+        ['left', start],
+        ['right', end],
+      ]
+    }
+    case 'inset-block': {
+      const start = lengthPercentageOrAutoToValue(decl.value.blockStart)
+      const end = lengthPercentageOrAutoToValue(decl.value.blockEnd)
+      if (start === null || end === null) return []
+      return [
+        ['top', start],
+        ['bottom', end],
+      ]
+    }
+    case 'width':
+    case 'height':
+    case 'min-width':
+    case 'min-height':
+    case 'max-width':
+    case 'max-height': {
+      const v = sizeLikeToValue(decl.value)
+      if (v === null) return []
+      return [[kebabToCamel(decl.property), v]]
+    }
+    case 'gap': {
+      return expandGap(decl.value)
+    }
+    case 'row-gap':
+    case 'column-gap': {
+      const v = gapValueToValue(decl.value)
+      if (v === null) return []
+      return [[kebabToCamel(decl.property), v]]
+    }
+    case 'font-style': {
+      return [['fontStyle', decl.value.type]]
+    }
+    case 'display': {
+      return displayToEntries(decl.value)
+    }
+    case 'position': {
+      return [['position', decl.value.type]]
+    }
+    case 'font-size': {
+      const px = fontSizeToPx(decl.value)
+      if (px === null) return []
+      return [['fontSize', px]]
+    }
+    case 'font-weight': {
+      return [['fontWeight', fontWeightToValue(decl.value)]]
+    }
+    case 'padding': {
+      return expandFourSided('padding', decl.value)
+    }
+    case 'margin': {
+      return expandFourSided('margin', decl.value)
+    }
+    case 'padding-inline': {
+      return expandLogicalInline('padding', decl.value)
+    }
+    case 'padding-block': {
+      return expandLogicalBlock('padding', decl.value)
+    }
+    case 'margin-inline': {
+      return expandLogicalInline('margin', decl.value)
+    }
+    case 'margin-block': {
+      return expandLogicalBlock('margin', decl.value)
+    }
+    case 'padding-top':
+    case 'padding-right':
+    case 'padding-bottom':
+    case 'padding-left':
+    case 'margin-top':
+    case 'margin-right':
+    case 'margin-bottom':
+    case 'margin-left': {
+      const v = lengthPercentageOrAutoToValue(decl.value)
+      if (v === null) return []
+      return [[kebabToCamel(decl.property), v]]
+    }
+    case 'border-radius': {
+      return expandBorderRadius(decl.value)
+    }
+    case 'border-top-left-radius':
+    case 'border-top-right-radius':
+    case 'border-bottom-left-radius':
+    case 'border-bottom-right-radius': {
+      const [xAxis] = decl.value
+      const v = dimensionPercentageToNumber(xAxis)
+      if (v === null) return []
+      return [[kebabToCamel(decl.property), v]]
+    }
+    case 'flex': {
+      return flexToEntries(decl.value)
+    }
+    case 'flex-grow':
+    case 'flex-shrink': {
+      return [[kebabToCamel(decl.property), decl.value]]
+    }
+    case 'flex-basis': {
+      const v = lengthPercentageOrAutoToValue(decl.value)
+      if (v === null) return []
+      return [['flexBasis', v]]
+    }
+    default: {
+      return (
+        dispatchLayoutDeclaration(decl) ??
+        dispatchTypographyDeclaration(decl) ??
+        dispatchColorPropertyDeclaration(decl) ??
+        dispatchBorderDeclaration(decl) ??
+        dispatchMotionDeclaration(decl) ??
+        []
+      )
+    }
+  }
+}

package/src/core/parser/gradient.ts

@@ -0,0 +1,148 @@
+/**
+ * Gradient-atom extractor.
+ *
+ * Tailwind v4's gradient system is encoded as a set of CSS custom
+ * properties Tailwind writes onto specific utility class rules:
+ *
+ *   .from-red-500       → `--tw-gradient-from: #ef4444`
+ *   .via-green-500      → `--tw-gradient-via:  #22c55e`
+ *   .to-blue-500        → `--tw-gradient-to:   #3b82f6`
+ *   .bg-gradient-to-r   → `--tw-gradient-position: to right`
+ *   .bg-linear-to-br    → `--tw-gradient-position: to bottom right`
+ *
+ * None of these set properties React Native can render (`backgroundImage:
+ * linear-gradient(...)` is web-only). Instead, rnwind treats them as
+ * **metadata**: the transformer strips gradient atoms from the JSX
+ * site's className and emits `colors={[...]} start={...} end={...}`
+ * props on the original component (user supplies `<LinearGradient>`
+ * from `expo-linear-gradient` or similar).
+ *
+ * This module walks a lightningcss declaration list, notices the
+ * `--tw-gradient-*` writes, and surfaces them as a compact
+ * {@link GradientAtomInfo} record the transformer can read per atom.
+ */
+
+import type { Declaration as LcDeclaration, TokenOrValue } from 'lightningcss'
+import { cssColorToString } from './color'
+
+/**
+ * The four roles an atom can play in a Tailwind v4 gradient. `from`,
+ * `via`, `to` carry a color. `direction` carries one of the 8 stock
+ * points (or a bare angle when Tailwind v4's `bg-linear-[angle]`
+ * syntax is used).
+ */
+export type GradientAtomInfo =
+  | { readonly role: 'from'; readonly color: string }
+  | { readonly role: 'via'; readonly color: string }
+  | { readonly role: 'to'; readonly color: string }
+  | { readonly role: 'direction'; readonly dir: GradientDirection }
+
+/**
+ * Eight stock corner directions Tailwind v4 ships. The transformer
+ * maps each to a `(start, end)` pair of unit-square points the
+ * expo-linear-gradient API expects. Unknown directions are surfaced as
+ * `'unknown'` so the transformer can skip them gracefully.
+ */
+export type GradientDirection =
+  | 'to-r'
+  | 'to-l'
+  | 'to-t'
+  | 'to-b'
+  | 'to-tr'
+  | 'to-tl'
+  | 'to-br'
+  | 'to-bl'
+  | 'unknown'
+
+/**
+ * Inspect a rule's declaration list for `--tw-gradient-*` writes and
+ * return the atom's role + data. Returns `null` for rules that don't
+ * belong to a gradient utility.
+ * @param declarations Declarations from one lightningcss style rule.
+ * @returns Gradient info, or null.
+ */
+function detectGradientAtom(declarations: readonly LcDeclaration[]): GradientAtomInfo | null {
+  for (const decl of declarations) {
+    if (decl.property !== 'custom') continue
+    const custom = decl.value as { name: { name: string } | string; value?: readonly TokenOrValue[] }
+    const name = typeof custom.name === 'string' ? custom.name : custom.name.name
+    if (!name.startsWith('--tw-gradient-')) continue
+    if (name === '--tw-gradient-from') return fromColor('from', custom.value)
+    if (name === '--tw-gradient-via') return fromColor('via', custom.value)
+    if (name === '--tw-gradient-to') return fromColor('to', custom.value)
+    if (name === '--tw-gradient-position') return fromDirection(custom.value)
+  }
+  return null
+}
+
+/**
+ * Extract a single color token from a custom-property value list and
+ * return the `{role, color}` record. Returns `null` when no color token
+ * is present (defensive — Tailwind always emits one, but future output
+ * shapes may not).
+ * @param role Target role (`from` / `via` / `to`).
+ * @param tokens Value tokens from the `--tw-gradient-*` declaration.
+ * @returns Gradient info, or null.
+ */
+function fromColor(role: 'from' | 'via' | 'to', tokens: readonly TokenOrValue[] | undefined): GradientAtomInfo | null {
+  if (!tokens) return null
+  for (const token of tokens) {
+    if (token.type !== 'color') continue
+    const color = cssColorToString(token.value as never)
+    if (!color) return null
+    return { role, color } as GradientAtomInfo
+  }
+  return null
+}
+
+/**
+ * Interpret a `--tw-gradient-position` value list as a direction tag.
+ * Tailwind emits plain idents (`to`, `right`, `bottom`, …) for the
+ * 8 stock corners.
+ * @param tokens Value tokens from `--tw-gradient-position`.
+ * @returns Direction record, or null when unrecognised.
+ */
+function fromDirection(tokens: readonly TokenOrValue[] | undefined): GradientAtomInfo | null {
+  if (!tokens) return null
+  const idents: string[] = []
+  for (const token of tokens) {
+    if (token.type !== 'token') continue
+    if (token.value.type === 'ident') idents.push(token.value.value as string)
+  }
+  const dir = directionFromIdents(idents)
+  if (!dir) return null
+  return { role: 'direction', dir }
+}
+
+/** Table of Tailwind-space direction idents → compact rnwind tag. */
+const DIRECTION_TABLE: Record<string, GradientDirection> = {
+  right: 'to-r',
+  left: 'to-l',
+  top: 'to-t',
+  bottom: 'to-b',
+  'top-right': 'to-tr',
+  'top-left': 'to-tl',
+  'bottom-right': 'to-br',
+  'bottom-left': 'to-bl',
+}
+
+/**
+ * Collapse the ident list Tailwind emits (`['to', 'right']`,
+ * `['to', 'bottom', 'right']`, etc.) into the compact tag the
+ * transformer hoists.
+ * @param idents Ident tokens from the declaration value.
+ * @returns One of the eight stock directions, `'unknown'`, or null.
+ */
+function directionFromIdents(idents: readonly string[]): GradientDirection | null {
+  if (idents.length === 0) return null
+  if (idents[0] !== 'to') return 'unknown'
+  // Tailwind v4 appends `in <colourspace>` for colour interpolation
+  // (`to right in oklab`). Strip everything from the `in` keyword on
+  // — it's irrelevant for the point mapping.
+  const inIndex = idents.indexOf('in')
+  const rest = idents.slice(1, inIndex === -1 ? idents.length : inIndex)
+  if (rest.length === 0 || rest.length > 2) return 'unknown'
+  return DIRECTION_TABLE[rest.join('-')] ?? 'unknown'
+}
+
+export { detectGradientAtom }