@wix/zero-config-implementation 1.102.0 → 1.104.0

package/package.json

@@ -4,7 +4,7 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "version": "1.102.0",
+  "version": "1.104.0",
   "description": "Core library for extracting component manifests from JS and CSS files",
   "type": "module",
   "main": "dist/index.js",
@@ -106,5 +106,5 @@
       ]
     }
   },
-  "falconPackageHash": "96d9e739c8567fd3813b698d6e9d84d175e3def2393dbaec37e6a9e7"
+  "falconPackageHash": "d233fc718503fd69a8efbad0624d506a5450fdd5e310b5b11cf42832"
 }

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

@@ -393,4 +393,31 @@ describe('resolveLonghand', () => {
       expect(resolveLonghand('textDecorationLine', values)).toBe('overline')
     })
   })
+
+  describe('flexDirection extraction from flex-flow shorthand', () => {
+    it('extracts the lone direction keyword', () => {
+      expect(resolveLonghand('flexDirection', new Map([['flexFlow', 'column']]))).toBe('column')
+    })
+
+    it('ignores token order — direction keyword can appear anywhere', () => {
+      expect(resolveLonghand('flexDirection', new Map([['flexFlow', 'wrap column-reverse']]))).toBe('column-reverse')
+    })
+
+    it('defaults to row when the shorthand carries only a wrap keyword', () => {
+      expect(resolveLonghand('flexDirection', new Map([['flexFlow', 'wrap']]))).toBe('row')
+      expect(resolveLonghand('flexDirection', new Map([['flexFlow', 'nowrap']]))).toBe('row')
+    })
+
+    it('returns undefined when flexFlow is absent', () => {
+      expect(resolveLonghand('flexDirection', new Map())).toBeUndefined()
+    })
+
+    it('prefers literal flexDirection over extracting from shorthand', () => {
+      const values = new Map([
+        ['flexDirection', 'row-reverse'],
+        ['flexFlow', 'column wrap'],
+      ])
+      expect(resolveLonghand('flexDirection', values)).toBe('row-reverse')
+    })
+  })
 })

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

@@ -217,14 +217,20 @@ const fromTextDecorationLine: Fallback = (values) => {
 
 /**
  * `flex-flow: <flex-direction> || <flex-wrap>` — order is free and either
- * part may be omitted. Pick out just the direction keyword for the schema.
+ * part may be omitted. Pick out the direction keyword for the schema, or the
+ * spec's default (`row`) when the developer only wrote a wrap keyword, e.g.
+ * `flex-flow: wrap`.
  */
 const FLEX_DIRECTION_KEYWORDS = new Set(['row', 'row-reverse', 'column', 'column-reverse'])
+const DEFAULT_FLEX_DIRECTION = 'row'
 
 const fromFlexFlowDirection: Fallback = (values) => {
   const shorthand = values.get('flexFlow')
   if (shorthand === undefined) return undefined
-  return splitTopLevelTokens(shorthand).find((token) => FLEX_DIRECTION_KEYWORDS.has(token.toLowerCase()))
+  const directionToken = splitTopLevelTokens(shorthand).find((token) =>
+    FLEX_DIRECTION_KEYWORDS.has(token.toLowerCase()),
+  )
+  return directionToken ?? DEFAULT_FLEX_DIRECTION
 }
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/converters/data-item-builder.ts

@@ -117,7 +117,7 @@ function applyResolvedTypeToDataItem(
       return handleObjectType(dataItem, resolvedType, propUsages, propPath)
 
     case 'union':
-      return handleUnionType(dataItem, resolvedType, propInfo)
+      return handleUnionType({ dataItem, resolvedType, propInfo, propUsages, propPath })
 
     case 'function':
       handleFunctionType(dataItem, propInfo, bindings)
@@ -290,11 +290,19 @@ function handleObjectType(
  * Handles union types by detecting special patterns (boolean literals,
  * string literal enums) or falling back to the first valid member type.
  */
-function handleUnionType(
-  dataItem: DataItem,
-  resolvedType: ResolvedType,
-  propInfo: PropInfo,
-): Result<void, ParseErrorInstance> {
+function handleUnionType({
+  dataItem,
+  resolvedType,
+  propInfo,
+  propUsages,
+  propPath,
+}: {
+  dataItem: DataItem
+  resolvedType: ResolvedType
+  propInfo: PropInfo
+  propUsages?: TrackingStores['propUsages']
+  propPath?: string
+}): Result<void, ParseErrorInstance> {
   if (!resolvedType.types || resolvedType.types.length === 0) {
     dataItem.dataType = DATA_TYPE.text
     dataItem.text = {}
@@ -341,7 +349,7 @@ function handleUnionType(
   // For other unions, use the first valid type
   const firstValidType = validTypes[0]
   if (firstValidType) {
-    return applyResolvedTypeToDataItem(dataItem, firstValidType, propInfo)
+    return applyResolvedTypeToDataItem(dataItem, firstValidType, propInfo, propUsages, propPath)
   }
 
   dataItem.dataType = DATA_TYPE.text

package/src/information-extractors/react/extractors/css-properties.test.ts

@@ -6,6 +6,7 @@ import type { ExtractedElement } from './core/tree-builder'
 import {
   enrichContainerProperties,
   enrichFlexProperties,
+  enrichMarginProperties,
   getCssPropertiesForTag,
   getDefaultDisplayForTag,
   hasContainerLikeDisplay,
@@ -541,3 +542,71 @@ describe('enrichContainerProperties', () => {
     expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.paddingTop)
   })
 })
+
+describe('enrichMarginProperties', () => {
+  it('adds the block-axis margins to a non-replaced inline element whose matched CSS changes display to block', () => {
+    const elements = [createElementWithCssProperties('span', 'display: block')]
+
+    const [enrichedElement] = enrichMarginProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginBottom)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineStart)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineEnd)
+  })
+
+  it('adds the full margin family to a non-replaced inline element whose matched CSS changes display to inline-flex', () => {
+    const elements = [createElementWithCssProperties('span', 'display: inline-flex')]
+
+    const [enrichedElement] = enrichMarginProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginBottom)
+  })
+
+  it('keeps only the horizontal margins when a span stays inline', () => {
+    const elements = [createElementWithCssProperties('span', 'display: inline')]
+
+    const [enrichedElement] = enrichMarginProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineStart)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineEnd)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginBottom)
+  })
+
+  it('removes all margin from an element whose matched CSS changes display to an internal table value', () => {
+    const elements = [createElementWithCssProperties('div', 'display: table-cell')]
+
+    const [enrichedElement] = enrichMarginProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginBottom)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineStart)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineEnd)
+  })
+
+  it('leaves the tag-default margin guess alone when no CSS declares display', () => {
+    const elements = [createElementWithCssProperties('span', '')]
+
+    const [enrichedElement] = enrichMarginProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginInlineStart)
+    expect(cssData.relevant).not.toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+  })
+
+  it('corrects margin via the --display root convention, not just a literal display declaration', () => {
+    const elements = [createElementWithCssProperties('span', '--display: block')]
+
+    const [enrichedElement] = enrichMarginProperties(elements)
+    const cssData = enrichedElement.extractorData.get('css-properties') as { relevant: string[] }
+
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginTop)
+    expect(cssData.relevant).toContain(CSS_PROPERTIES.CSS_PROPERTY_TYPE.marginBottom)
+  })
+})

package/src/information-extractors/react/extractors/css-properties.ts

@@ -135,26 +135,35 @@ const MARGIN_UNSUPPORTED_DISPLAY_VALUES = new Set([
 ])
 
 /**
- * Margin properties relevant to a tag's default display. Internal table
+ * Margin properties relevant to a given `display` value. Internal table
  * display values (`tr`, `thead`/`tbody`/`tfoot`, `col`/`colgroup`, `td`/`th`)
  * don't honor margin at all. Non-replaced inline elements (`span`, `a`, …)
  * only honor the horizontal (inline) margins — `margin-top`/`margin-bottom`
  * have no effect on them. Replaced inline elements (`img`, `video`, …) honor
  * margin on every side, same as a block box.
  */
-function getMarginPropertiesForTag(tag: string): string[] {
-  const normalizedTag = tag.toLowerCase()
-  const defaultDisplay = getDefaultDisplayForTag(normalizedTag)
-
-  if (MARGIN_UNSUPPORTED_DISPLAY_VALUES.has(defaultDisplay)) {
+function getMarginPropertiesForDisplay(displayValue: string, isReplacedElement: boolean): string[] {
+  const normalizedDisplayValue = normalizeDisplayValue(displayValue)
+  if (MARGIN_UNSUPPORTED_DISPLAY_VALUES.has(normalizedDisplayValue)) {
     return []
   }
-  if (defaultDisplay === 'inline' && !MEDIA_TAGS.has(normalizedTag)) {
+  if (normalizedDisplayValue === 'inline' && !isReplacedElement) {
     return HORIZONTAL_MARGIN_CSS_PROPERTIES
   }
   return MARGIN_CSS_PROPERTIES
 }
 
+/**
+ * Margin properties relevant to a tag's default display, used as the
+ * best-effort guess at element creation time, before CSS matching has run.
+ * `enrichMarginProperties` corrects this once the effective display —
+ * matched CSS, including the `--display` root convention — is known.
+ */
+function getMarginPropertiesForTag(tag: string): string[] {
+  const normalizedTag = tag.toLowerCase()
+  return getMarginPropertiesForDisplay(getDefaultDisplayForTag(normalizedTag), MEDIA_TAGS.has(normalizedTag))
+}
+
 /**
  * Child-layout controls for flex/grid containers, added post-hoc by
  * `enrichFlexProperties` once the element's resolved `display` is known.
@@ -654,6 +663,49 @@ export function enrichContainerProperties(elements: ExtractedElement[]): Extract
   })
 }
 
+/**
+ * Replaces whatever margin properties are currently in `existing` with the
+ * ones relevant to `marginProperties` — used by `enrichMarginProperties` to
+ * correct the tag-default guess once the effective display is known.
+ */
+function withMarginProperties(existing: string[], marginProperties: string[]): string[] {
+  const withoutMargin = existing.filter((property) => !(MARGIN_CSS_PROPERTIES as string[]).includes(property))
+  return [...withoutMargin, ...marginProperties]
+}
+
+/**
+ * Walks the element tree and corrects margin properties from the tag-default
+ * guess made at creation time to the element's effective display — matched
+ * CSS, including the `--display` root convention. A non-replaced inline
+ * element (e.g. `<span>`) whose matched CSS changes display to `block` or
+ * `flex` gains the block-axis margins it was missing; conversely, an element
+ * whose effective display becomes an internal table value loses margin
+ * entirely. Must be called after CSS selector matching (requires
+ * css-matcher data).
+ */
+export function enrichMarginProperties(elements: ExtractedElement[]): ExtractedElement[] {
+  return elements.map((element) => {
+    const matcherData = element.extractorData.get('css-matcher') as MatchedCssData | undefined
+    const cssData = element.extractorData.get('css-properties') as CssPropertiesData | undefined
+
+    if (cssData && matcherData && hasEffectiveDisplayDeclaration(matcherData)) {
+      const effectiveDisplay = resolveEffectiveDisplayValue(matcherData)
+      if (effectiveDisplay !== undefined) {
+        const isReplacedElement = MEDIA_TAGS.has(element.tag.toLowerCase())
+        const marginProperties = getMarginPropertiesForDisplay(effectiveDisplay, isReplacedElement)
+        element.extractorData.set('css-properties', {
+          relevant: withMarginProperties(cssData.relevant, marginProperties),
+        })
+      }
+    }
+
+    return {
+      ...element,
+      children: enrichMarginProperties(element.children),
+    }
+  })
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Factory
 // ─────────────────────────────────────────────────────────────────────────────

package/src/information-extractors/react/extractors/index.ts

@@ -29,6 +29,7 @@ export {
   enrichGapProperties,
   enrichContainerProperties,
   enrichFlexProperties,
+  enrichMarginProperties,
   resolveDisplayValue,
   getDefaultDisplayForTag,
   ROOT_DISPLAY_CUSTOM_PROPERTY,

package/src/information-extractors/react/index.ts

@@ -19,6 +19,7 @@ export {
   enrichGapProperties,
   enrichContainerProperties,
   enrichFlexProperties,
+  enrichMarginProperties,
   resolveDisplayValue,
   getDefaultDisplayForTag,
   ROOT_DISPLAY_CUSTOM_PROPERTY,

package/src/manifest-pipeline.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 
 import type { ComponentInfo } from './information-extractors/ts'
-import type { PropInfo } from './information-extractors/ts/types'
+import type { PropInfo, ResolvedType } from './information-extractors/ts/types'
 
 import {
   type ExtractedElement,
@@ -12,6 +12,7 @@ import {
   enrichContainerProperties,
   enrichFlexProperties,
   enrichGapProperties,
+  enrichMarginProperties,
   runExtractors,
 } from './information-extractors/react'
 import type { CoupledComponentInfo, CoupledProp, DOMBinding, TrackingStores } from './information-extractors/react'
@@ -150,7 +151,8 @@ export function processComponent(
   if (html && extractedElements.length > 0 && css.length > 0) {
     try {
       const matchResult = matchCssSelectors(html, extractedElements, css)
-      const containerEnrichedElements = enrichContainerProperties(matchResult.elements)
+      const marginEnrichedElements = enrichMarginProperties(matchResult.elements)
+      const containerEnrichedElements = enrichContainerProperties(marginEnrichedElements)
       const gapEnrichedElements = enrichGapProperties(containerEnrichedElements)
       const flexEnrichedElements = enrichFlexProperties(gapEnrichedElements)
       enhancedInfo = {
@@ -225,10 +227,11 @@ function processElementPropsWrites(
     if (!relativePath) continue
 
     // Resolve the PropInfo for this leaf prop by walking the type tree
-    const propInfo = resolveInnerPropInfo(elementPropsInfo, relativePath)
-    if (!propInfo) continue
+    const resolvedProp = resolveInnerPropInfo(elementPropsInfo, relativePath)
+    if (!resolvedProp) continue
+    const { propInfo, relativePropPath } = resolvedProp
 
-    const elementPropsPath = extractParentElementPropsPath(relativePath)
+    const elementPropsPath = extractParentElementPropsPath(relativePropPath)
     if (!elementPropsPath) continue
     const bindings = extractBindings(writeInfo)
 
@@ -246,7 +249,7 @@ function processElementPropsWrites(
         entry.props[leafName] = {
           ...propInfo,
           logicOnly: false,
-          propPath: path,
+          propPath: `props.elementProps.${relativePropPath}`,
         }
       }
     }
@@ -260,29 +263,44 @@ function processElementPropsWrites(
  * e.g., path "navbar.items" -> walk elementProps type -> navbar property -> items property
  * Handles recursive nesting: "hamburgerMenu.elementProps.hamburgerCloseButton.label"
  */
-function resolveInnerPropInfo(elementPropsPropInfo: PropInfo, relativePath: string): PropInfo | null {
+function resolveInnerPropInfo(
+  elementPropsPropInfo: PropInfo,
+  relativePath: string,
+): { propInfo: PropInfo; relativePropPath: string } | null {
   const segments = relativePath.split('.')
-  let currentType = elementPropsPropInfo.resolvedType
+  let currentType = unwrapOptionalType(elementPropsPropInfo.resolvedType)
 
-  for (let i = 0; i < segments.length; i++) {
-    const segment = segments[i]
+  for (let segmentIndex = 0; segmentIndex < segments.length; segmentIndex++) {
+    const segment = segments[segmentIndex]
     if (!currentType.properties) return null
 
     const propInfo = currentType.properties[segment]
     if (!propInfo) return null
 
-    // If this is the last segment, return the PropInfo
-    if (i === segments.length - 1) {
-      return propInfo
+    // A11y is one semantic data item. Its tracked DOM writes point at fields
+    // such as next.a11y.ariaLabel, but the type has no property tree to descend.
+    // Keep the parent path so the builder can collect only the used attributes.
+    const propType = unwrapOptionalType(propInfo.resolvedType)
+    const isA11y = propType.kind === 'semantic' && propType.value === 'A11y'
+    if (segmentIndex === segments.length - 1 || isA11y) {
+      return { propInfo, relativePropPath: segments.slice(0, segmentIndex + 1).join('.') }
     }
 
     // Otherwise, descend into this property's resolved type
-    currentType = propInfo.resolvedType
+    currentType = propType
   }
 
   return null
 }
 
+function unwrapOptionalType(resolvedType: ResolvedType): ResolvedType {
+  if (resolvedType.kind !== 'union') return resolvedType
+  const definedTypes = resolvedType.types?.filter(
+    (member) => !(member.kind === 'primitive' && (member.value === 'undefined' || member.value === 'null')),
+  )
+  return definedTypes?.length === 1 ? definedTypes[0] : resolvedType
+}
+
 function extractBindings(
   writeInfo: TrackingStores['propUsages'] extends Map<string, infer V> ? V : never,
 ): DOMBinding[] {