@wix/zero-config-implementation 1.88.0 → 1.90.0

package/src/information-extractors/react/extractors/state-markers.ts

@@ -2,9 +2,8 @@
  * Design-state inference from React-extractor signals.
  *
  * The new design (Notion: "New Design") supports only the four native states
- * (hover/focus/disabled/invalid) and derives them purely from the React side:
- * html tag, role attribute, and event handlers. The CSS extractor is not
- * involved.
+ * (hover/focus/disabled/invalid). React signals provide the defaults; a caller
+ * may additionally report a focus state the component author wrote in CSS.
  */
 
 import type { ExtractedElement } from './core/tree-builder'
@@ -65,6 +64,25 @@ const INTERACTIVE_EVENT_HANDLERS = new Set([
   'onSubmit',
 ])
 
+// Elements that get a focus design state without the author asking for one: the
+// ones whose focused appearance is part of using them. Mirrored in the wix-app
+// skill's `editor-react-component/DESIGN-STATES.md` eligibility table.
+const DEFAULT_FOCUS_TAGS = new Set(['select', 'textarea'])
+
+const DEFAULT_FOCUS_ROLES = new Set([
+  'checkbox',
+  'radio',
+  'switch',
+  'slider',
+  'spinbutton',
+  'textbox',
+  'searchbox',
+  'combobox',
+  'listbox',
+])
+
+const INPUT_TYPES_WITHOUT_FOCUS_STATE = new Set(['hidden', 'button', 'submit', 'reset', 'image'])
+
 const DISABLEABLE_TAGS = new Set(['button', 'input', 'select', 'textarea', 'fieldset'])
 
 const DISABLEABLE_ROLES = new Set(['button', 'switch', 'checkbox', 'radio', 'menuitem', 'tab', 'option', 'link'])
@@ -102,6 +120,15 @@ function hasInteractiveSignal(tag: string, role: string | undefined, eventHandle
   return eventHandlers.some((handler) => INTERACTIVE_EVENT_HANDLERS.has(handler))
 }
 
+function hasDefaultFocusSignal(element: ExtractedElement, tag: string, role: string | undefined): boolean {
+  if (role !== undefined) return DEFAULT_FOCUS_ROLES.has(role)
+  if (DEFAULT_FOCUS_TAGS.has(tag)) return true
+  if (tag !== 'input') return false
+
+  const inputType = element.attributes.type?.toLowerCase()
+  return inputType === undefined || !INPUT_TYPES_WITHOUT_FOCUS_STATE.has(inputType)
+}
+
 function hasDisableableSignal(tag: string, role: string | undefined): boolean {
   if (DISABLEABLE_TAGS.has(tag)) return true
   if (role !== undefined && DISABLEABLE_ROLES.has(role)) return true
@@ -114,14 +141,19 @@ function hasValidatableSignal(tag: string): boolean {
 
 /**
  * Decides which of the four native states the given element supports, based on
- * its tag, role, and event handlers.
+ * its tag, role, event handlers, and `authoredFocus` — a paired focus modifier
+ * the component author wrote in CSS, which opts an interactive element into the
+ * focus state it does not get by default.
  *
  * Two attribute-level overrides apply:
  *   - `role="presentation"` / `role="none"` opts the element out of every state.
  *   - `tabindex="-1"` suppresses `focus` only (the element is programmatically
  *     focusable but not via keyboard tab).
  */
-export function inferSupportedNativeStates(element: ExtractedElement): SupportedNativeStates {
+export function inferSupportedNativeStates(
+  element: ExtractedElement,
+  { authoredFocus = false }: { authoredFocus?: boolean } = {},
+): SupportedNativeStates {
   const tag = element.tag.toLowerCase()
   const role = getRole(element)
 
@@ -135,7 +167,7 @@ export function inferSupportedNativeStates(element: ExtractedElement): Supported
 
   return {
     hover: interactive,
-    focus: interactive && !isUntabbable,
+    focus: interactive && !isUntabbable && (hasDefaultFocusSignal(element, tag, role) || authoredFocus),
     disabled: hasDisableableSignal(tag, role),
     invalid: hasValidatableSignal(tag),
   }

package/src/validators/editor-element-validator.test.ts

@@ -0,0 +1,142 @@
+import type { CssCustomPropertyItem, EditorElement, ElementItem } from '@wix/react-component-schema'
+import { CSS_PROPERTIES, ELEMENTS } from '@wix/react-component-schema'
+import { describe, expect, it } from 'vitest'
+
+import { ValidationError } from '../errors'
+import { validateEditorElement } from './editor-element-validator'
+
+function buildMinimalEditorElement(overrides: Partial<EditorElement> = {}): EditorElement {
+  return {
+    selector: '.root',
+    displayName: 'Test Component',
+    ...overrides,
+  }
+}
+
+function buildInlineElementItem(overrides: Partial<ElementItem> = {}): ElementItem {
+  return {
+    elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
+    inlineElement: {
+      selector: '.child',
+      displayName: 'Child',
+    },
+    ...overrides,
+  }
+}
+
+function buildCssCustomPropertyItem(cssPropertyType: CssCustomPropertyItem['cssPropertyType']): CssCustomPropertyItem {
+  return { cssPropertyType }
+}
+
+describe('validateEditorElement', () => {
+  it('does not throw for a valid minimal editorElement', () => {
+    const editorElement = buildMinimalEditorElement()
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).not.toThrow()
+  })
+
+  it('does not throw when cssCustomProperties have valid property types', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        color: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.color),
+        size: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.length),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).not.toThrow()
+  })
+
+  it('throws ValidationError when a cssCustomProperty has UNKNOWN cssPropertyType', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        brokenProp: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(ValidationError)
+  })
+
+  it('includes the field path in the error message for UNKNOWN cssPropertyType', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        brokenProp: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(
+      'editorElement.cssCustomProperties.brokenProp',
+    )
+  })
+
+  it('throws ValidationError when a cssCustomProperty is missing cssPropertyType', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        missingTypeProp: {} as CssCustomPropertyItem,
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(ValidationError)
+  })
+
+  it('throws ValidationError when an elements entry has UNKNOWN elementType', () => {
+    const editorElement = buildMinimalEditorElement({
+      elements: {
+        child: {
+          elementType: ELEMENTS.ELEMENT_TYPE.UNKNOWN_ElementType,
+          inlineElement: { selector: '.child', displayName: 'Child' },
+        },
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(ValidationError)
+  })
+
+  it('throws ValidationError when an elements entry is missing elementType', () => {
+    const editorElement = buildMinimalEditorElement({
+      elements: {
+        child: buildInlineElementItem({ elementType: undefined }),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(ValidationError)
+  })
+
+  it('collects all violations and throws once with all of them listed', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        badProp: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+      },
+      elements: {
+        child: {
+          elementType: ELEMENTS.ELEMENT_TYPE.UNKNOWN_ElementType,
+          inlineElement: { selector: '.child', displayName: 'Child' },
+        },
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(
+      /editorElement\.cssCustomProperties\.badProp.*\n.*editorElement\.elements\.child/s,
+    )
+  })
+
+  it('validates nested inline element cssCustomProperties recursively', () => {
+    const editorElement = buildMinimalEditorElement({
+      elements: {
+        child: {
+          elementType: ELEMENTS.ELEMENT_TYPE.inlineElement,
+          inlineElement: {
+            selector: '.child',
+            displayName: 'Child',
+            cssCustomProperties: {
+              nestedBad: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+            },
+          },
+        },
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'TestComponent')).toThrow(
+      'editorElement.elements.child.inlineElement.cssCustomProperties.nestedBad',
+    )
+  })
+
+  it('includes the component name in the error message', () => {
+    const editorElement = buildMinimalEditorElement({
+      cssCustomProperties: {
+        badProp: buildCssCustomPropertyItem(CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType),
+      },
+    })
+    expect(() => validateEditorElement(editorElement, 'MyButton')).toThrow('MyButton')
+  })
+})

package/src/validators/editor-element-validator.ts

@@ -0,0 +1,64 @@
+import type {
+  CssCustomPropertyItem,
+  EditorReactComponent,
+  ElementItem,
+  InlineElement,
+} from '@wix/react-component-schema'
+import { CSS_PROPERTIES, ELEMENTS } from '@wix/react-component-schema'
+
+import { ValidationError } from '../errors'
+
+type RawEditorElement = NonNullable<EditorReactComponent['editorElement']>
+type AnyElement = RawEditorElement | InlineElement
+
+export function validateEditorElement(editorElement: RawEditorElement, componentName: string): void {
+  const violations = collectElementViolations(editorElement, 'editorElement')
+  if (violations.length === 0) return
+
+  const violationList = violations.map((violation) => `  - ${violation}`).join('\n')
+  throw new ValidationError(`Component "${componentName}" produced an invalid editorElement:\n${violationList}`, {
+    props: { phase: 'conversion' },
+  })
+}
+
+function collectElementViolations(element: AnyElement, elementPath: string): string[] {
+  return [
+    ...validateCssCustomProperties(element.cssCustomProperties, elementPath),
+    ...validateElementsMap(element.elements, elementPath),
+  ]
+}
+
+function validateCssCustomProperties(
+  cssCustomProperties: Record<string, CssCustomPropertyItem> | undefined,
+  elementPath: string,
+): string[] {
+  if (!cssCustomProperties) return []
+
+  const violations: string[] = []
+  for (const [propKey, propValue] of Object.entries(cssCustomProperties)) {
+    const unknownType = CSS_PROPERTIES.CSS_PROPERTY_TYPE.UNKNOWN_CssPropertyType
+    if (!propValue.cssPropertyType || propValue.cssPropertyType === unknownType) {
+      violations.push(`${elementPath}.cssCustomProperties.${propKey}: cssPropertyType is not set or UNKNOWN`)
+    }
+  }
+  return violations
+}
+
+function validateElementsMap(elements: Record<string, ElementItem> | undefined, elementPath: string): string[] {
+  if (!elements) return []
+
+  const violations: string[] = []
+  for (const [elementKey, elementItem] of Object.entries(elements)) {
+    const itemPath = `${elementPath}.elements.${elementKey}`
+    const unknownType = ELEMENTS.ELEMENT_TYPE.UNKNOWN_ElementType
+
+    if (!elementItem.elementType || elementItem.elementType === unknownType) {
+      violations.push(`${itemPath}: elementType is not set or UNKNOWN`)
+    }
+
+    if (elementItem.inlineElement) {
+      violations.push(...collectElementViolations(elementItem.inlineElement, `${itemPath}.inlineElement`))
+    }
+  }
+  return violations
+}