@wix/zero-config-implementation 1.61.0 → 1.63.0

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.61.0",
+  "version": "1.63.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -80,5 +80,5 @@
       ]
     }
   },
-  "falconPackageHash": "274e5da8e4ba5ae90001de1df05e55e4cd4e281605bae183858538b7"
+  "falconPackageHash": "fc05eca6895716f63fc1c075f50bf661142e5d08ab108de4d195403e"
 }

package/src/converters/css-longhand-resolver.test.ts

@@ -0,0 +1,361 @@
+import { describe, expect, it } from 'vitest'
+import { resolveLonghand, splitAxis, splitBox, splitCorners, splitTopLevelTokens } from './css-longhand-resolver'
+
+describe('splitTopLevelTokens', () => {
+  it('splits a single token', () => {
+    expect(splitTopLevelTokens('1rem')).toEqual(['1rem'])
+  })
+
+  it('splits multiple plain tokens', () => {
+    expect(splitTopLevelTokens('1px solid red')).toEqual(['1px', 'solid', 'red'])
+  })
+
+  it('keeps calc() intact even with embedded spaces', () => {
+    expect(splitTopLevelTokens('calc(1rem + 2px) 4px')).toEqual(['calc(1rem + 2px)', '4px'])
+  })
+
+  it('keeps var() intact', () => {
+    expect(splitTopLevelTokens('var(--x) var(--y)')).toEqual(['var(--x)', 'var(--y)'])
+  })
+
+  it('keeps nested parens intact', () => {
+    expect(splitTopLevelTokens('rgb(0 0 0) calc(1px + var(--y))')).toEqual(['rgb(0 0 0)', 'calc(1px + var(--y))'])
+  })
+
+  it('handles leading and trailing whitespace', () => {
+    expect(splitTopLevelTokens('  1px   2px  ')).toEqual(['1px', '2px'])
+  })
+})
+
+describe('splitBox', () => {
+  it('one value: applies to all sides', () => {
+    expect(splitBox('1rem')).toEqual({ top: '1rem', right: '1rem', bottom: '1rem', left: '1rem' })
+  })
+
+  it('two values: block / inline', () => {
+    expect(splitBox('1rem 2rem')).toEqual({ top: '1rem', right: '2rem', bottom: '1rem', left: '2rem' })
+  })
+
+  it('three values: top / horizontal / bottom', () => {
+    expect(splitBox('1px 2px 3px')).toEqual({ top: '1px', right: '2px', bottom: '3px', left: '2px' })
+  })
+
+  it('four values: top / right / bottom / left', () => {
+    expect(splitBox('1px 2px 3px 4px')).toEqual({ top: '1px', right: '2px', bottom: '3px', left: '4px' })
+  })
+
+  it('preserves calc() as a single token', () => {
+    expect(splitBox('calc(10px + 1rem) 2rem')).toEqual({
+      top: 'calc(10px + 1rem)',
+      right: '2rem',
+      bottom: 'calc(10px + 1rem)',
+      left: '2rem',
+    })
+  })
+
+  it('preserves var() tokens', () => {
+    expect(splitBox('var(--x) var(--y)')).toEqual({
+      top: 'var(--x)',
+      right: 'var(--y)',
+      bottom: 'var(--x)',
+      left: 'var(--y)',
+    })
+  })
+
+  it('returns undefined for unsupported token counts', () => {
+    expect(splitBox('')).toBeUndefined()
+    expect(splitBox('1px 2px 3px 4px 5px')).toBeUndefined()
+  })
+})
+
+describe('splitAxis', () => {
+  it('one value: both ends', () => {
+    expect(splitAxis('1rem')).toEqual({ start: '1rem', end: '1rem' })
+  })
+
+  it('two values: start / end', () => {
+    expect(splitAxis('4px 8px')).toEqual({ start: '4px', end: '8px' })
+  })
+
+  it('returns undefined for zero or > 2 tokens', () => {
+    expect(splitAxis('')).toBeUndefined()
+    expect(splitAxis('1px 2px 3px')).toBeUndefined()
+  })
+})
+
+describe('splitCorners', () => {
+  it('one value: applies to all corners', () => {
+    expect(splitCorners('4px')).toEqual({ tl: '4px', tr: '4px', br: '4px', bl: '4px' })
+  })
+
+  it('two values: tl/br and tr/bl', () => {
+    expect(splitCorners('4px 8px')).toEqual({ tl: '4px', tr: '8px', br: '4px', bl: '8px' })
+  })
+
+  it('three values: tl / (tr & bl) / br', () => {
+    expect(splitCorners('4px 8px 12px')).toEqual({ tl: '4px', tr: '8px', br: '12px', bl: '8px' })
+  })
+
+  it('four values: tl / tr / br / bl', () => {
+    expect(splitCorners('4px 8px 12px 16px')).toEqual({ tl: '4px', tr: '8px', br: '12px', bl: '16px' })
+  })
+
+  it('drops elliptical second radii after /', () => {
+    expect(splitCorners('4px 8px 12px 16px / 1px 2px 3px 4px')).toEqual({
+      tl: '4px',
+      tr: '8px',
+      br: '12px',
+      bl: '16px',
+    })
+  })
+
+  it('returns undefined for unsupported token counts', () => {
+    expect(splitCorners('')).toBeUndefined()
+  })
+})
+
+describe('resolveLonghand', () => {
+  it('returns direct hits without consulting shorthand rules', () => {
+    const values = new Map([
+      ['paddingTop', '5px'],
+      ['padding', '10px'],
+    ])
+    expect(resolveLonghand('paddingTop', values)).toBe('5px')
+  })
+
+  it('returns undefined when target is unknown and absent', () => {
+    expect(resolveLonghand('marginTop', new Map())).toBeUndefined()
+  })
+
+  it('returns undefined when no rule produces a value', () => {
+    expect(resolveLonghand('paddingTop', new Map())).toBeUndefined()
+  })
+
+  describe('padding family', () => {
+    it('paddingTop falls back through paddingBlockStart → paddingBlock → padding', () => {
+      expect(resolveLonghand('paddingTop', new Map([['paddingBlockStart', '1px']]))).toBe('1px')
+      expect(resolveLonghand('paddingTop', new Map([['paddingBlock', '4px 8px']]))).toBe('4px')
+      expect(resolveLonghand('paddingTop', new Map([['padding', '1rem 2rem']]))).toBe('1rem')
+    })
+
+    it('paddingBottom falls back through paddingBlockEnd → paddingBlock → padding', () => {
+      expect(resolveLonghand('paddingBottom', new Map([['paddingBlockEnd', '2px']]))).toBe('2px')
+      expect(resolveLonghand('paddingBottom', new Map([['paddingBlock', '4px 8px']]))).toBe('8px')
+      expect(resolveLonghand('paddingBottom', new Map([['padding', '1rem 2rem']]))).toBe('1rem')
+    })
+
+    it('paddingInlineStart falls back through paddingLeft → paddingInline → padding', () => {
+      expect(resolveLonghand('paddingInlineStart', new Map([['paddingLeft', '7px']]))).toBe('7px')
+      expect(resolveLonghand('paddingInlineStart', new Map([['paddingInline', '12px']]))).toBe('12px')
+      expect(resolveLonghand('paddingInlineStart', new Map([['paddingInline', '12px 24px']]))).toBe('12px')
+      expect(resolveLonghand('paddingInlineStart', new Map([['padding', '1px 2px 3px 4px']]))).toBe('4px')
+    })
+
+    it('paddingInlineEnd falls back through paddingRight → paddingInline → padding', () => {
+      expect(resolveLonghand('paddingInlineEnd', new Map([['paddingRight', '9px']]))).toBe('9px')
+      expect(resolveLonghand('paddingInlineEnd', new Map([['paddingInline', '12px 24px']]))).toBe('24px')
+      expect(resolveLonghand('paddingInlineEnd', new Map([['padding', '1px 2px 3px 4px']]))).toBe('2px')
+    })
+  })
+
+  describe('border-radius corners', () => {
+    it('maps borderTopLeftRadius to borderStartStartRadius (LTR / horizontal-tb)', () => {
+      expect(resolveLonghand('borderStartStartRadius', new Map([['borderTopLeftRadius', '5px']]))).toBe('5px')
+    })
+
+    it('falls back to borderRadius corner split', () => {
+      const values = new Map([['borderRadius', '4px 8px 12px 16px']])
+      expect(resolveLonghand('borderStartStartRadius', values)).toBe('4px')
+      expect(resolveLonghand('borderStartEndRadius', values)).toBe('8px')
+      expect(resolveLonghand('borderEndEndRadius', values)).toBe('12px')
+      expect(resolveLonghand('borderEndStartRadius', values)).toBe('16px')
+    })
+  })
+
+  describe('border sides', () => {
+    it('borderTop falls back through borderBlockStart → border', () => {
+      expect(resolveLonghand('borderTop', new Map([['borderBlockStart', '2px dashed blue']]))).toBe('2px dashed blue')
+      expect(resolveLonghand('borderTop', new Map([['border', '1px solid red']]))).toBe('1px solid red')
+    })
+
+    it('borderInlineStart falls back through borderLeft → borderInline → border', () => {
+      expect(resolveLonghand('borderInlineStart', new Map([['borderLeft', '3px dotted black']]))).toBe(
+        '3px dotted black',
+      )
+      expect(resolveLonghand('borderInlineStart', new Map([['borderInline', '1px solid grey']]))).toBe('1px solid grey')
+      expect(resolveLonghand('borderInlineStart', new Map([['border', '1px solid red']]))).toBe('1px solid red')
+    })
+  })
+
+  describe('background', () => {
+    it('falls back to backgroundColor when background is absent', () => {
+      expect(resolveLonghand('background', new Map([['backgroundColor', '#abcdef']]))).toBe('#abcdef')
+    })
+
+    it('prefers literal background over backgroundColor', () => {
+      const values = new Map([
+        ['background', '#001'],
+        ['backgroundColor', '#abcdef'],
+      ])
+      expect(resolveLonghand('background', values)).toBe('#001')
+    })
+  })
+
+  describe('font composition from longhands', () => {
+    it('composes size and family alone', () => {
+      const values = new Map([
+        ['fontSize', '14px'],
+        ['fontFamily', 'Arial'],
+      ])
+      expect(resolveLonghand('font', values)).toBe('14px Arial')
+    })
+
+    it('includes weight before size', () => {
+      const values = new Map([
+        ['fontSize', '16px'],
+        ['fontFamily', "'Helvetica Neue'"],
+        ['fontWeight', '600'],
+      ])
+      expect(resolveLonghand('font', values)).toBe("600 16px 'Helvetica Neue'")
+    })
+
+    it('joins size and line-height with /', () => {
+      const values = new Map([
+        ['fontSize', '14px'],
+        ['fontFamily', 'sans-serif'],
+        ['lineHeight', '1.5'],
+      ])
+      expect(resolveLonghand('font', values)).toBe('14px/1.5 sans-serif')
+    })
+
+    it('combines weight, size/line-height, family in spec order', () => {
+      const values = new Map([
+        ['fontStyle', 'italic'],
+        ['fontWeight', '700'],
+        ['fontSize', '20px'],
+        ['lineHeight', '1.3'],
+        ['fontFamily', 'serif'],
+      ])
+      expect(resolveLonghand('font', values)).toBe('italic 700 20px/1.3 serif')
+    })
+
+    it("omits modifiers with literal value 'normal'", () => {
+      const values = new Map([
+        ['fontStyle', 'normal'],
+        ['fontWeight', 'normal'],
+        ['fontSize', '16px'],
+        ['lineHeight', 'normal'],
+        ['fontFamily', 'Arial'],
+      ])
+      expect(resolveLonghand('font', values)).toBe('16px Arial')
+    })
+
+    it('returns undefined when fontSize is missing (strict)', () => {
+      const values = new Map([['fontFamily', 'Arial']])
+      expect(resolveLonghand('font', values)).toBeUndefined()
+    })
+
+    it('returns undefined when fontFamily is missing (strict)', () => {
+      const values = new Map([['fontSize', '14px']])
+      expect(resolveLonghand('font', values)).toBeUndefined()
+    })
+
+    it('returns undefined when only optional modifiers are present', () => {
+      const values = new Map([
+        ['fontWeight', '700'],
+        ['fontStyle', 'italic'],
+      ])
+      expect(resolveLonghand('font', values)).toBeUndefined()
+    })
+
+    it('prefers literal font shorthand over longhand composition', () => {
+      const values = new Map([
+        ['font', '400 14px Arial'],
+        ['fontSize', '99px'],
+        ['fontFamily', 'WrongFont'],
+      ])
+      expect(resolveLonghand('font', values)).toBe('400 14px Arial')
+    })
+  })
+
+  describe('gap composition from row-gap + column-gap', () => {
+    it('composes two distinct axis values in row/column order', () => {
+      const values = new Map([
+        ['rowGap', '8px'],
+        ['columnGap', '10px'],
+      ])
+      expect(resolveLonghand('gap', values)).toBe('8px 10px')
+    })
+
+    it('collapses to a single value when both axes are equal', () => {
+      const values = new Map([
+        ['rowGap', '4px'],
+        ['columnGap', '4px'],
+      ])
+      expect(resolveLonghand('gap', values)).toBe('4px')
+    })
+
+    it('returns undefined when rowGap is missing (strict)', () => {
+      const values = new Map([['columnGap', '10px']])
+      expect(resolveLonghand('gap', values)).toBeUndefined()
+    })
+
+    it('returns undefined when columnGap is missing (strict)', () => {
+      const values = new Map([['rowGap', '8px']])
+      expect(resolveLonghand('gap', values)).toBeUndefined()
+    })
+
+    it('prefers literal gap shorthand over longhand composition', () => {
+      const values = new Map([
+        ['gap', '12px'],
+        ['rowGap', '99px'],
+        ['columnGap', '99px'],
+      ])
+      expect(resolveLonghand('gap', values)).toBe('12px')
+    })
+  })
+
+  describe('textDecorationLine extraction from text-decoration shorthand', () => {
+    it('extracts the lone line keyword', () => {
+      expect(resolveLonghand('textDecorationLine', new Map([['textDecoration', 'underline']]))).toBe('underline')
+    })
+
+    it('extracts the line keyword and drops style + color tokens', () => {
+      expect(resolveLonghand('textDecorationLine', new Map([['textDecoration', 'underline wavy red']]))).toBe(
+        'underline',
+      )
+    })
+
+    it('ignores token order — line keyword can appear anywhere', () => {
+      expect(resolveLonghand('textDecorationLine', new Map([['textDecoration', 'red wavy underline']]))).toBe(
+        'underline',
+      )
+    })
+
+    it('keeps multiple line keywords joined (e.g. underline + overline)', () => {
+      expect(resolveLonghand('textDecorationLine', new Map([['textDecoration', 'underline overline']]))).toBe(
+        'underline overline',
+      )
+    })
+
+    it('extracts `none`', () => {
+      expect(resolveLonghand('textDecorationLine', new Map([['textDecoration', 'none']]))).toBe('none')
+    })
+
+    it('returns undefined when shorthand has no line keyword (just color/style)', () => {
+      expect(resolveLonghand('textDecorationLine', new Map([['textDecoration', 'red']]))).toBeUndefined()
+    })
+
+    it('returns undefined when textDecoration is absent', () => {
+      expect(resolveLonghand('textDecorationLine', new Map())).toBeUndefined()
+    })
+
+    it('prefers literal textDecorationLine over extracting from shorthand', () => {
+      const values = new Map([
+        ['textDecorationLine', 'overline'],
+        ['textDecoration', 'underline red'],
+      ])
+      expect(resolveLonghand('textDecorationLine', values)).toBe('overline')
+    })
+  })
+})

package/src/converters/css-longhand-resolver.ts

@@ -0,0 +1,286 @@
+import type { CSS_PROPERTIES } from '@wix/react-component-schema'
+import { type Value, generate, parse } from 'css-tree'
+import { SHORTHAND_FALLBACKS } from './css-shorthand-composer'
+
+/**
+ * Resolves a CSS longhand to its default value by reading the developer's
+ * parsed CSS map. Accepts whatever shorthand the developer happened to write
+ * (`padding`, `padding-block`, `padding-block-start`, …) and splits it into
+ * the longhand piece the schema asked for. Returns `undefined` when no
+ * shorthand can satisfy the target.
+ *
+ * Example. Developer wrote `padding: 10px 20px`. Schema asks for `paddingTop`.
+ *   1. Direct hit on `paddingTop` — miss.
+ *   2. Walk FALLBACKS['paddingTop'] in order:
+ *        fromKey('paddingBlockStart')      → miss
+ *        fromAxis('paddingBlock', 'start') → miss
+ *        fromBox('padding', 'top')         → splitBox('10px 20px').top = '10px' ✅
+ *
+ * Writing-mode assumption: `horizontal-tb` + LTR (CSS default). The logical-
+ * to-physical equivalences this file relies on (e.g. `padding-block-start` ↔
+ * `padding-top`, `padding-left` ↔ `padding-inline-start`) only hold under
+ * that mode. RTL and vertical writing modes are out of scope.
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Every property name the editor's schema knows about — the values of
+ * `CSS_PROPERTIES.CSS_PROPERTY_TYPE`. Used to type the FALLBACKS table's
+ * target keys so a typo or rename in the schema fails compilation here.
+ *
+ * Note: source-side names in factory calls (`paddingBlock`, `borderBlockStart`,
+ * etc.) stay plain strings because the developer can write any valid CSS
+ * property, including names the schema doesn't have controls for.
+ */
+type CssPropertyName = (typeof CSS_PROPERTIES.CSS_PROPERTY_TYPE)[keyof typeof CSS_PROPERTIES.CSS_PROPERTY_TYPE]
+
+type BoxValues = { top: string; right: string; bottom: string; left: string }
+type AxisValues = { start: string; end: string }
+type CornerValues = { tl: string; tr: string; br: string; bl: string }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tokenizer
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Splits a CSS value on top-level whitespace, keeping function calls intact.
+ *   `1px solid red`           → ['1px', 'solid', 'red']
+ *   `calc(1rem + 2px) 4px`    → ['calc(1rem + 2px)', '4px']
+ *   `rgb(0 0 0) var(--y)`     → ['rgb(0 0 0)', 'var(--y)']
+ *
+ * Backed by css-tree's value AST so function calls (calc/var/rgb/…) stay as
+ * one opaque `Function` node — no manual paren tracking. Whitespace and
+ * operators are filtered out; operator-aware callers (like splitCorners,
+ * which stops at `/`) handle the AST themselves.
+ */
+export function splitTopLevelTokens(value: string): string[] {
+  const tokens: string[] = []
+  try {
+    const valueAst = parse(value, { context: 'value' }) as Value
+    valueAst.children.forEach((child) => {
+      if (child.type === 'WhiteSpace' || child.type === 'Operator') return
+      tokens.push(generate(child))
+    })
+  } catch {
+    // Malformed value — let callers see the empty result and fall back conservatively.
+  }
+  return tokens
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Splitters — parse a shorthand value into named parts
+//
+// Each splitter applies the CSS spec's 1-to-N-value expansion rule for its
+// shorthand family. Unsupported token counts return `undefined` so callers
+// fall back conservatively instead of guessing.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * `padding` / `margin` / `inset` — the four-sided box.
+ *   1 value:  `padding: 10px`               → all four sides 10px
+ *   2 values: `padding: 10px 20px`          → block (top/bottom) 10px, inline (right/left) 20px
+ *   3 values: `padding: 10px 20px 30px`     → top 10px, right & left 20px, bottom 30px
+ *   4 values: `padding: 10px 20px 30px 40px` → clockwise from top
+ */
+export function splitBox(value: string): BoxValues | undefined {
+  const tokens = splitTopLevelTokens(value)
+  switch (tokens.length) {
+    case 1:
+      return { top: tokens[0], right: tokens[0], bottom: tokens[0], left: tokens[0] }
+    case 2:
+      return { top: tokens[0], right: tokens[1], bottom: tokens[0], left: tokens[1] }
+    case 3:
+      return { top: tokens[0], right: tokens[1], bottom: tokens[2], left: tokens[1] }
+    case 4:
+      return { top: tokens[0], right: tokens[1], bottom: tokens[2], left: tokens[3] }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * `padding-block`, `padding-inline`, `margin-block`, `margin-inline` — a single axis.
+ *   1 value:  `padding-block: 10px`     → start 10px, end 10px
+ *   2 values: `padding-block: 4px 8px`  → start 4px, end 8px
+ */
+export function splitAxis(value: string): AxisValues | undefined {
+  const tokens = splitTopLevelTokens(value)
+  switch (tokens.length) {
+    case 1:
+      return { start: tokens[0], end: tokens[0] }
+    case 2:
+      return { start: tokens[0], end: tokens[1] }
+    default:
+      return undefined
+  }
+}
+
+/**
+ * `border-radius` — the four corners. Keys: tl, tr, br, bl.
+ * Anything after `/` describes elliptical second radii and is dropped (v1).
+ *   1 corner:  `border-radius: 4px`                  → all four corners 4px
+ *   2 corners: `border-radius: 4px 8px`              → tl & br 4px, tr & bl 8px
+ *   3 corners: `border-radius: 4px 8px 12px`         → tl 4px, tr & bl 8px, br 12px
+ *   4 corners: `border-radius: 4px 8px 12px 16px`    → clockwise from top-left
+ */
+export function splitCorners(value: string): CornerValues | undefined {
+  const tokens: string[] = []
+  try {
+    const valueAst = parse(value, { context: 'value' }) as Value
+    for (const child of valueAst.children) {
+      if (child.type === 'WhiteSpace') continue
+      // `/` separates the corner radii from the elliptical second radii (v1: drop them).
+      if (child.type === 'Operator' && child.value === '/') break
+      tokens.push(generate(child))
+    }
+  } catch {
+    return undefined
+  }
+  switch (tokens.length) {
+    case 1:
+      return { tl: tokens[0], tr: tokens[0], br: tokens[0], bl: tokens[0] }
+    case 2:
+      return { tl: tokens[0], tr: tokens[1], br: tokens[0], bl: tokens[1] }
+    case 3:
+      return { tl: tokens[0], tr: tokens[1], br: tokens[2], bl: tokens[1] }
+    case 4:
+      return { tl: tokens[0], tr: tokens[1], br: tokens[2], bl: tokens[3] }
+    default:
+      return undefined
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Fallback factories — used to build the FALLBACKS table declaratively
+//
+// A Fallback is a function: given the developer's CSS map, produce a default
+// value (or `undefined` when its source isn't present). Four flavors, each
+// named after what it pulls out:
+//
+//   fromKey('paddingBlockStart')          → look up that key, return its value as-is
+//   fromBox('padding', 'top')             → look up 'padding', split it, return the top piece
+//   fromAxis('paddingBlock', 'start')     → look up 'paddingBlock', split it, return the start piece
+//   fromCorner('borderRadius', 'tl')      → look up 'borderRadius', split it, return the top-left corner
+//
+// This is the layer that lets FALLBACKS read like a sentence per row, instead
+// of a wall of inline arrow functions.
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Fallback = (values: Map<string, string>) => string | undefined
+
+function fromKey(from: string): Fallback {
+  return (values) => values.get(from)
+}
+
+function fromBox(from: string, side: keyof BoxValues): Fallback {
+  return (values) => {
+    const value = values.get(from)
+    return value === undefined ? undefined : splitBox(value)?.[side]
+  }
+}
+
+function fromAxis(from: string, end: keyof AxisValues): Fallback {
+  return (values) => {
+    const value = values.get(from)
+    return value === undefined ? undefined : splitAxis(value)?.[end]
+  }
+}
+
+function fromCorner(from: string, corner: keyof CornerValues): Fallback {
+  return (values) => {
+    const value = values.get(from)
+    return value === undefined ? undefined : splitCorners(value)?.[corner]
+  }
+}
+
+/**
+ * `text-decoration: <line> || <style> || <color>` — order is free and any
+ * subset is valid. The schema asks for `textDecorationLine` specifically, so
+ * we filter the shorthand's tokens down to just the line-keyword ones.
+ *
+ * Closed set of legal line keywords per the CSS spec (case-insensitive).
+ */
+const TEXT_DECORATION_LINE_KEYWORDS = new Set(['none', 'underline', 'overline', 'line-through', 'blink'])
+
+const fromTextDecorationLine: Fallback = (values) => {
+  const shorthand = values.get('textDecoration')
+  if (shorthand === undefined) return undefined
+  const lineTokens = splitTopLevelTokens(shorthand).filter((token) =>
+    TEXT_DECORATION_LINE_KEYWORDS.has(token.toLowerCase()),
+  )
+  if (lineTokens.length === 0) return undefined
+  return lineTokens.join(' ')
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Resolution table
+//
+// For each schema longhand, an ordered list of fallbacks to try when the
+// developer didn't write that longhand literally. The resolver walks them
+// top-to-bottom and returns the first non-undefined result.
+//
+// Order matters: most specific source first, broadest source last — this
+// mirrors CSS's own "more specific wins" cascade behavior.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const FALLBACKS: Partial<Record<CssPropertyName, Fallback[]>> = {
+  // Padding — block axis is physical (top/bottom), inline axis is logical (start/end).
+  paddingTop: [fromKey('paddingBlockStart'), fromAxis('paddingBlock', 'start'), fromBox('padding', 'top')],
+  paddingBottom: [fromKey('paddingBlockEnd'), fromAxis('paddingBlock', 'end'), fromBox('padding', 'bottom')],
+  paddingInlineStart: [fromKey('paddingLeft'), fromAxis('paddingInline', 'start'), fromBox('padding', 'left')],
+  paddingInlineEnd: [fromKey('paddingRight'), fromAxis('paddingInline', 'end'), fromBox('padding', 'right')],
+
+  // Border radius — schema uses all-logical corner names; physical names map under LTR/horizontal-tb.
+  borderStartStartRadius: [fromKey('borderTopLeftRadius'), fromCorner('borderRadius', 'tl')],
+  borderStartEndRadius: [fromKey('borderTopRightRadius'), fromCorner('borderRadius', 'tr')],
+  borderEndStartRadius: [fromKey('borderBottomLeftRadius'), fromCorner('borderRadius', 'bl')],
+  borderEndEndRadius: [fromKey('borderBottomRightRadius'), fromCorner('borderRadius', 'br')],
+
+  // Border sides — these are themselves shorthands (<width> || <style> || <color>).
+  // The schema treats them as one opaque value, so `border: 1px solid red` flows
+  // through verbatim to every side.
+  borderTop: [fromKey('borderBlockStart'), fromKey('border')],
+  borderBottom: [fromKey('borderBlockEnd'), fromKey('border')],
+  borderInlineStart: [fromKey('borderLeft'), fromKey('borderInline'), fromKey('border')],
+  borderInlineEnd: [fromKey('borderRight'), fromKey('borderInline'), fromKey('border')],
+
+  // Background — populate the schema's `background` from `background-color` when
+  // the developer only wrote the color.
+  background: [fromKey('backgroundColor')],
+
+  // Text-decoration — `text-decoration: underline wavy red` carries line, style,
+  // and color in one declaration. Pick out just the line tokens for the schema.
+  textDecorationLine: [fromTextDecorationLine],
+
+  // Shorthand targets (e.g. `font`) live in css-shorthand-composer.ts and are
+  // merged in here — composer-driven, conceptually the inverse of the rows above.
+  ...SHORTHAND_FALLBACKS,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Try the literal longhand first (covers the case where the developer wrote
+ * the exact key the schema is asking for). On a miss, walk the target's
+ * fallbacks and return the first non-undefined result. Returns `undefined`
+ * when nothing matches — the caller then emits an empty `cssProperties.<name>`
+ * entry, matching pre-resolver behavior for unknown cases.
+ */
+export function resolveLonghand(target: string, values: Map<string, string>): string | undefined {
+  const literal = values.get(target)
+  if (literal !== undefined) return literal
+
+  const fallbacks = FALLBACKS[target as CssPropertyName]
+  if (!fallbacks) return undefined
+
+  for (const fallback of fallbacks) {
+    const resolved = fallback(values)
+    if (resolved !== undefined) return resolved
+  }
+  return undefined
+}