@wix/react-component-utils

Runtime helpers and small utilities for Wix React components: merging manifests defaults into props at runtime, applying defaults onto extracted editor manifest payloads, accessibility field normalization, and a generic recursive merge.

Install

Peers: react ^18 or ^19.

yarn add @wix/react-component-utils

Public API

| Export | Role | |--------|------| | withDefaults | Higher-order component: merges default props into runtime props (fills missing values). | | withEditorElementDefaults | Copies an editor manifest element and injects default structure (data, nested elements with props). Manifest-specific rules, not a generic deep merge. | | withFallbackPlaceholder | Higher-order component: renders a placeholder when required data fields are missing, and an error placeholder when the wrapped component throws. | | merge | Recursive merge into the first argument (mutates target, returns it). Plain objects ({}, Object.create(null) lineage) and arrays merge by index; undefined in sources does not clear existing keys on target. | | convertA11yKeysToHtmlFormat | Maps accessibility shapes into HTML-oriented records (see a11y implementation). | | useStableId | Returns a stable id for ARIA wiring and form labels. Uses React.useId on React 18+; falls back to a post-mount counter on React 17. | | DefaultsError / DefaultsErrorPhase | Typed errors when default merging fails; callers fall back to the original props or manifest fragment. |

useStableId

import { useStableId } from '@wix/react-component-utils'

export function FormField({ id, label, value, onChange }: Props) {
  const inputId = useStableId(id)
  return (
    <>
      <label htmlFor={inputId}>{label}</label>
      <input id={inputId} value={value} onChange={onChange} />
    </>
  )
}

Pass id from props when the caller supplies one (it wins verbatim); the hook generates one otherwise.

SSR caveat (React 17 only): React 17 has no useId, so the fallback generates the id in a post-mount effect — useStableId() returns '' during SSR and a real id after hydration. If the id must be present in the server-rendered HTML (e.g. ARIA wiring on a statically rendered page), pass an overrideId from the caller. On React 18+ the hook delegates to React.useId and is fully SSR-stable.

merge vs withEditorElementDefaults

Use merge when you want ordinary recursive merging of plain data structures into an existing object.

Use withEditorElementDefaults only for editor manifest payloads: it skips keys such as elements.props when applying data, only fills defaultValue where appropriate, and only walks nested inlineElement / refElement branches.

Layout

• src/defaults/ — manifest + runtime default helpers
• src/merge/ — merge implementation
• src/utils/ — internal helpers shared by merge and defaults
• src/a11y/ — accessibility helpers
• src/fallback-placeholder/ — withFallbackPlaceholder HOC and placeholder UI

Development

From repo root (see AGENTS.md):

yarn workspace @wix/react-component-utils build
yarn workspace @wix/react-component-utils test
yarn workspace @wix/react-component-utils lint