@wix/builder-presets-polyfill-wrapper

A React wrapper component that polyfills CSS Container Style Queries for presets. It is designed to close the gap between browsers without native container style query support, ensuring consistent visual layouts.

Design & Browser Compatibility

Native CSS Container Style Queries (CSQ) are a powerful mechanism to style elements depending on custom property state on parent container elements. However, global browser support is not yet uniform.

This package provides a lightweight React wrapper (PresetsPolyfillWrapper) that:

• Uses feature detection via supportsContainerStyleQueries() to determine if the client's browser natively supports CSS Container Style Queries.
• If native support is present, the wrapper transparently returns a zero-overhead passthrough fragment (<>{children}</>).
• If native support is missing, it dynamically applies a robust JS-based polyfill to emulate container style query behavior.

Implementation Details

1. Reusing Core Engine Logic

Rather than re-implementing CSS parser and selector evaluation logic, this package imports and wraps the proven, high-performance polyfill engine from @wix/builder-presets-polyfill (the same logic that powers native site viewer environments in Thunderbolt).

2. Preventing Visual Flashing (useLayoutEffect)

To avoid a visual flash of unstyled/un-polyfilled elements (FOUC) when a page mounts, the polyfill logic is initialized inside a React useLayoutEffect hook.

Because useLayoutEffect fires synchronously after all DOM mutations but before the browser paints the screen, the initial polyfill stamp occurs instantly. This guarantees that elements appear in their final, fully-styled state upon their very first visible paint.

3. Dynamic Maintenance (Observers)

To ensure that polyfilled presets remain synchronized and accurate during the lifecycle of the component, two observers are registered:

• ResizeObserver (builderComponentPolyfillResizeObserver): Monitors component resize events and re-evaluates container style rules accordingly, maintaining accurate layouts on dimension changes.
• MutationObserver (builderComponentPresetsPolyfillMutationObserver): Monitors the widget DOM subtree to detect late-mounted or dynamically injected child elements, polyfilling them on the fly.

Both observers are automatically disposed of during the cleanup phase of the hook to prevent any potential memory leaks.

Usage

import React from 'react'
import { createPresetsPolyfillWrapper } from '@wix/builder-presets-polyfill-wrapper'

const PresetsPolyfillWrapper = createPresetsPolyfillWrapper(
  widgetRootId,
  presetsPolyfillConfig
)

export default function MyWidget({ children }) {
  return (
    <PresetsPolyfillWrapper>
      {children}
    </PresetsPolyfillWrapper>
  )
}