@wix/zero-config-implementation 1.87.0 → 1.89.0

package/package.json

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

package/src/converters/custom-states-builder.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import type { ExtractedElement } from '../information-extractors/react'
 import type { CoupledProp } from '../information-extractors/react/types'
-import { type CustomClassTrigger, buildCustomStatesBlock } from './custom-states-builder'
+import { buildCustomStatesBlock } from './custom-states-builder'
+import type { StateClassTrigger } from './state-class-trigger'
 
 function elementWithClass(classAttribute: string): ExtractedElement {
   return { attributes: { class: classAttribute } } as unknown as ExtractedElement
@@ -11,7 +12,7 @@ function booleanStateProp(name: string): CoupledProp {
   return { name, type: 'boolean', isStateTrigger: true } as unknown as CoupledProp
 }
 
-function classTrigger(baseSelector: string, modifier: string, isCssModule = false): CustomClassTrigger {
+function classTrigger(baseSelector: string, modifier: string, isCssModule = false): StateClassTrigger {
   return { baseSelector, modifier, isCssModule }
 }
 

package/src/converters/custom-states-builder.ts

@@ -18,20 +18,17 @@
 
 import type { States } from '@wix/react-component-schema'
 import { kebabCase } from 'case-anything'
-import type { StateClassRule } from '../information-extractors/css/types'
 import type { CoupledProp, ExtractedElement } from '../information-extractors/react'
-import { isGlobalSemanticClass, stateNameFromModifier } from '../utils/css-class'
+import { stateNameFromModifier } from '../utils/css-class'
+import { type StateClassTrigger, elementStateClassList, matchesStateBase } from './state-class-trigger'
 import { formatDisplayName } from './utils'
 
-/** A custom-class trigger tagged with whether its source file is a CSS module. */
-export type CustomClassTrigger = StateClassRule & { isCssModule: boolean }
-
 interface BuildCustomStatesParams {
   element: ExtractedElement
   /** Prop triggers in scope for this element (root-level `ElementState<>` props; `[]` for inner elements). */
   propTriggers: CoupledProp[]
   /** Custom-class triggers (modifiers with no paired native pseudo) across all CSS files. */
-  classTriggers: CustomClassTrigger[]
+  classTriggers: StateClassTrigger[]
 }
 
 export function buildCustomStatesBlock({
@@ -43,9 +40,10 @@ export function buildCustomStatesBlock({
 
   // Class triggers that target this element, keyed by their derived state name,
   // so prop triggers can look up their matching class.
-  const elementClassTriggers = new Map<string, CustomClassTrigger>()
+  const classList = elementStateClassList(element)
+  const elementClassTriggers = new Map<string, StateClassTrigger>()
   for (const rule of classTriggers) {
-    if (!elementMatchesBase(element, rule.baseSelector, rule.isCssModule)) continue
+    if (!matchesStateBase(classList, rule)) continue
     elementClassTriggers.set(stateNameFromModifier(rule.modifier), rule)
   }
 
@@ -84,34 +82,3 @@ export function buildCustomStatesBlock({
 function stateNameFromProp(propName: string): string {
   return kebabCase(propName)
 }
-
-/**
- * Checks whether an element's rendered class list matches a simple single-class
- * base selector (e.g. `.root`, `.custom-states`).
- *
- * Exact class match always counts. For CSS-module files the Vite hash patterns also
- * count: `localName_HASH`, `_localName_HASH`, and the double-underscore `localName__HASH`
- * form. The catch is that `localName__HASH` is syntactically identical to a BEM child
- * class (`localName__child`) — which denotes a *different* element and must NOT match the
- * block's base selector. We disambiguate by shape: a real BEM child is an all-lowercase
- * semantic name (`isGlobalSemanticClass`), whereas a module hash carries uppercase / other
- * non-kebab characters. So only genuine BEM children are excluded; hashed base classes match.
- */
-function elementMatchesBase(element: ExtractedElement, baseSelector: string, isCssModule: boolean): boolean {
-  const match = baseSelector.match(/^\.([\w-]+)$/)
-  if (!match) return false
-
-  const localName = match[1]
-  const classList = element.attributes.class?.split(/\s+/).filter(Boolean) ?? []
-  return classList.some((className) => {
-    if (className === localName) return true
-    if (!isCssModule) return false
-    // Genuine BEM child (`localName__<lowercase-element>`) → a different element, exclude it.
-    // A double-underscore module hash (`localName__<hash>`) is NOT semantic, so it falls through.
-    const isBemChild =
-      (className.startsWith(`${localName}__`) || className.startsWith(`_${localName}__`)) &&
-      isGlobalSemanticClass(className.replace(/^_/, ''))
-    if (isBemChild) return false
-    return className.startsWith(`${localName}_`) || className.startsWith(`_${localName}_`)
-  })
-}

package/src/converters/state-class-trigger.ts

@@ -0,0 +1,41 @@
+import type { StateClassRule } from '../information-extractors/css/types'
+import type { ExtractedElement } from '../information-extractors/react'
+import { isGlobalSemanticClass } from '../utils/css-class'
+
+/** A CSS state-class rule tagged with whether its source file is a CSS module. */
+export type StateClassTrigger = StateClassRule & { isCssModule: boolean }
+
+/** The element's rendered class list, split once so many triggers can be matched against it. */
+export function elementStateClassList(element: ExtractedElement): string[] {
+  return element.attributes.class?.split(/\s+/).filter(Boolean) ?? []
+}
+
+/**
+ * Checks whether a rendered class list matches a trigger's simple single-class
+ * base selector (e.g. `.root`, `.custom-states`).
+ *
+ * Exact class matches always count. For CSS-module files the Vite hash patterns also
+ * count: `localName_HASH`, `_localName_HASH`, and the double-underscore `localName__HASH`
+ * form. The catch is that `localName__HASH` is syntactically identical to a BEM child
+ * class (`localName__child`) — which denotes a *different* element and must NOT match the
+ * block's base selector. We disambiguate by shape: a real BEM child is an all-lowercase
+ * semantic name (`isGlobalSemanticClass`), whereas a module hash carries uppercase / other
+ * non-kebab characters. So only genuine BEM children are excluded; hashed base classes match.
+ */
+export function matchesStateBase(classList: string[], { baseSelector, isCssModule }: StateClassTrigger): boolean {
+  const match = baseSelector.match(/^\.([\w-]+)$/)
+  if (!match) return false
+
+  const localName = match[1]
+  return classList.some((className) => {
+    if (className === localName) return true
+    if (!isCssModule) return false
+
+    const isBemChild =
+      (className.startsWith(`${localName}__`) || className.startsWith(`_${localName}__`)) &&
+      isGlobalSemanticClass(className.replace(/^_/, ''))
+    if (isBemChild) return false
+
+    return className.startsWith(`${localName}_`) || className.startsWith(`_${localName}_`)
+  })
+}

package/src/converters/states-builder.test.ts

@@ -0,0 +1,96 @@
+import { NATIVE_STATE_TYPE } from '@wix/react-component-schema'
+import { describe, expect, it } from 'vitest'
+import type { ExtractedElement } from '../information-extractors/react'
+import type { PropTrackerData } from '../information-extractors/react/extractors/prop-tracker'
+import type { StateClassTrigger } from './state-class-trigger'
+import { buildStatesBlock } from './states-builder'
+
+function makeElement(input: { tag: string; className: string; attributes?: Record<string, string> }): ExtractedElement {
+  const propTrackerData: PropTrackerData = {
+    tag: input.tag,
+    boundProps: [],
+    concatenatedAttrs: new Map(),
+    eventHandlers: [],
+  }
+  return {
+    traceId: 'trace-0',
+    name: 'root',
+    tag: input.tag,
+    attributes: { ...input.attributes, class: input.className },
+    extractorData: new Map([['prop-tracker', propTrackerData]]),
+    children: [],
+  }
+}
+
+function focusTrigger(input: {
+  baseSelector: string
+  modifier: string
+  isCssModule?: boolean
+}): StateClassTrigger {
+  return { ...input, isCssModule: input.isCssModule ?? false, pseudoClass: 'focus' }
+}
+
+describe('buildStatesBlock', () => {
+  it('does not emit focus for a button without an authored focus state', () => {
+    const states = buildStatesBlock(makeElement({ tag: 'button', className: 'card-button' }), 'card-button', [])
+
+    expect(states).toEqual({
+      hover: {
+        displayName: 'Hover',
+        className: 'card-button--hover',
+        pseudoClass: NATIVE_STATE_TYPE.hover,
+      },
+      disabled: {
+        displayName: 'Disabled',
+        className: 'card-button--disabled',
+        pseudoClass: NATIVE_STATE_TYPE.disabled,
+      },
+    })
+  })
+
+  it('emits default focus for an input field', () => {
+    const states = buildStatesBlock(makeElement({ tag: 'input', className: 'card-input' }), 'card-input', [])
+
+    expect(states?.focus).toEqual({
+      displayName: 'Focus',
+      className: 'card-input--focus',
+      pseudoClass: NATIVE_STATE_TYPE.focus,
+    })
+  })
+
+  it('uses a matching authored focus modifier to opt in a button', () => {
+    const states = buildStatesBlock(makeElement({ tag: 'button', className: 'button_HASH' }), 'card-button', [
+      focusTrigger({ baseSelector: '.button', modifier: 'card-button--focus', isCssModule: true }),
+    ])
+
+    expect(states?.focus).toEqual({
+      displayName: 'Focus',
+      className: 'card-button--focus',
+      pseudoClass: NATIVE_STATE_TYPE.focus,
+    })
+  })
+
+  it('synthesizes the state className even when the authored modifier differs', () => {
+    const states = buildStatesBlock(makeElement({ tag: 'button', className: 'card-button' }), 'card-button', [
+      focusTrigger({ baseSelector: '.card-button', modifier: 'legacy-focus' }),
+    ])
+
+    expect(states?.focus?.className).toBe('card-button--focus')
+  })
+
+  it('ignores an authored focus modifier on a non-interactive element', () => {
+    const states = buildStatesBlock(makeElement({ tag: 'div', className: 'card-badge' }), 'card-badge', [
+      focusTrigger({ baseSelector: '.card-badge', modifier: 'card-badge--focus' }),
+    ])
+
+    expect(states).toBeUndefined()
+  })
+
+  it('ignores an authored focus modifier targeting another element', () => {
+    const states = buildStatesBlock(makeElement({ tag: 'button', className: 'secondary-button' }), 'secondary-button', [
+      focusTrigger({ baseSelector: '.primary-button', modifier: 'primary-button--focus' }),
+    ])
+
+    expect(states?.focus).toBeUndefined()
+  })
+})

package/src/converters/states-builder.ts

@@ -1,9 +1,10 @@
 /**
  * Builds the `states` block for the root EditorElement and inline elements.
  *
- * Native states only (hover/focus/disabled/invalid). Signals come from the
- * React extractor (tag, role, event handlers). The CSS extractor is not
- * consulted.
+ * Native states only (hover/focus/disabled/invalid). Default signals come from
+ * the React extractor (tag, role, event handlers); a paired CSS focus modifier
+ * opts an interactive element into the focus state. The CSS is a signal only —
+ * the emitted className is always synthesized, like every other native state.
  *
  * className follows BEM by appending `--<state>` to the element's own
  * semantic class. Component authors are expected to write inner elements
@@ -23,6 +24,7 @@ import {
   type SupportedNativeStates,
   inferSupportedNativeStates,
 } from '../information-extractors/react'
+import { type StateClassTrigger, elementStateClassList, matchesStateBase } from './state-class-trigger'
 
 const STATE_DISPLAY_NAMES = {
   hover: 'Hover',
@@ -40,8 +42,14 @@ const PSEUDO_CLASS_BY_STATE: Record<NativeStateName, NATIVE_STATE_TYPE> = {
   invalid: NATIVE_STATE_TYPE.invalid,
 }
 
-export function buildStatesBlock(element: ExtractedElement, semanticClass: string): States | undefined {
-  const supported = inferSupportedNativeStates(element)
+export function buildStatesBlock(
+  element: ExtractedElement,
+  semanticClass: string,
+  focusTriggers: StateClassTrigger[],
+): States | undefined {
+  const classList = elementStateClassList(element)
+  const authoredFocus = focusTriggers.some((trigger) => matchesStateBase(classList, trigger))
+  const supported = inferSupportedNativeStates(element, { authoredFocus })
   const states: States = {}
 
   for (const stateName of Object.keys(supported) as NativeStateName[]) {

package/src/converters/to-editor-component.ts

@@ -27,8 +27,9 @@ import { getDefaultDisplayForTag, resolveDisplayValue } from '../information-ext
 import { findPreferredSemanticClass, normalizeClassNames } from '../utils/css-class'
 import { buildActiveItemDisplayGroups, buildActiveItemIndexDisplayFilters } from './active-item-index-builder'
 import { resolveLonghand } from './css-longhand-resolver'
-import { type CustomClassTrigger, buildCustomStatesBlock } from './custom-states-builder'
+import { buildCustomStatesBlock } from './custom-states-builder'
 import { buildDataItem } from './data-item-builder'
+import type { StateClassTrigger } from './state-class-trigger'
 import { buildStatesBlock } from './states-builder'
 import { formatDisplayName } from './utils'
 
@@ -43,14 +44,26 @@ function mergeStates(native: States | undefined, custom: States | undefined): St
   return Object.keys(merged).length > 0 ? merged : undefined
 }
 
-/** Collects custom-class state triggers (modifiers with no paired native pseudo) across all CSS files. */
-function collectCustomClassTriggers(component: ComponentInfoWithCss): CustomClassTrigger[] {
-  return component.css.flatMap((cssInfo) =>
-    cssInfo.api
-      .getStateClasses()
-      .filter((rule) => rule.pseudoClass === undefined)
-      .map((rule) => ({ ...rule, isCssModule: cssInfo.isCssModule })),
+/** State-class triggers grouped by the builder that consumes them. */
+interface StateClassTriggers {
+  /** Modifiers paired with `:focus` — they opt an element into the native focus state. */
+  focus: StateClassTrigger[]
+  /** Modifiers with no paired pseudo-class — they denote custom (non-native) states. */
+  custom: StateClassTrigger[]
+}
+
+/**
+ * Collects state-class triggers across all CSS files, grouped up front so each element
+ * matches against only the rules its builder can use.
+ */
+function collectStateClassTriggers(component: ComponentInfoWithCss): StateClassTriggers {
+  const triggers = component.css.flatMap((cssInfo) =>
+    cssInfo.api.getStateClasses().map((rule) => ({ ...rule, isCssModule: cssInfo.isCssModule })),
   )
+  return {
+    focus: triggers.filter((rule) => rule.pseudoClass === 'focus'),
+    custom: triggers.filter((rule) => rule.pseudoClass === undefined),
+  }
 }
 
 // Props to exclude from data items (same as in element-data.ts)
@@ -77,7 +90,7 @@ function buildEditorElement(
   const childElements = rootElement.children
   const rootCustomProps = nearestCommonAncestorCustomProps.get(rootElement.traceId) ?? {}
 
-  const customClassTriggers = collectCustomClassTriggers(component)
+  const stateClassTriggers = collectStateClassTriggers(component)
 
   // Native states need a semantic block name to synthesize `<block>--<state>`; custom
   // class triggers don't (they carry the className verbatim and match the element
@@ -86,11 +99,11 @@ function buildEditorElement(
   const rootSemanticClasses = rootSemanticClass ? [rootSemanticClass] : []
   const rootStates = rootElement
     ? mergeStates(
-        rootSemanticClass ? buildStatesBlock(rootElement, rootSemanticClass) : undefined,
+        rootSemanticClass ? buildStatesBlock(rootElement, rootSemanticClass, stateClassTriggers.focus) : undefined,
         buildCustomStatesBlock({
           element: rootElement,
           propTriggers: Object.values(component.props).filter((prop) => prop.isStateTrigger),
-          classTriggers: customClassTriggers,
+          classTriggers: stateClassTriggers.custom,
         }),
       )
     : undefined
@@ -105,7 +118,7 @@ function buildEditorElement(
     elements: buildElements(
       childElements,
       nearestCommonAncestorCustomProps,
-      customClassTriggers,
+      stateClassTriggers,
       rootSemanticClasses,
       component.innerElementProps,
       component.propUsages,
@@ -176,7 +189,7 @@ function buildData(
 function buildElements(
   elements: ExtractedElement[],
   nearestCommonAncestorCustomProps: Map<string, Record<string, CssCustomPropertyItem>>,
-  customClassTriggers: CustomClassTrigger[],
+  stateClassTriggers: StateClassTriggers,
   ancestorSemanticClasses: string[],
   innerElementProps?: CoupledComponentInfo['innerElementProps'],
   propUsages?: TrackingStores['propUsages'],
@@ -208,8 +221,8 @@ function buildElements(
     // Inner-element custom states come from custom-class triggers only; prop
     // triggers (`ElementState<>`) are component-level and attach to the root.
     const states = mergeStates(
-      semanticClass ? buildStatesBlock(element, semanticClass) : undefined,
-      buildCustomStatesBlock({ element, propTriggers: [], classTriggers: customClassTriggers }),
+      semanticClass ? buildStatesBlock(element, semanticClass, stateClassTriggers.focus) : undefined,
+      buildCustomStatesBlock({ element, propTriggers: [], classTriggers: stateClassTriggers.custom }),
     )
 
     result[element.name] = {
@@ -231,7 +244,7 @@ function buildElements(
             ? buildElements(
                 element.children,
                 nearestCommonAncestorCustomProps,
-                customClassTriggers,
+                stateClassTriggers,
                 semanticClass ? [...ancestorSemanticClasses, semanticClass] : ancestorSemanticClasses,
                 innerElementProps,
                 propUsages,

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

@@ -27,12 +27,11 @@ function makeElement(input: {
 }
 
 describe('inferSupportedNativeStates', () => {
-  describe('hover + focus (interactive)', () => {
-    it('returns true for native form tags', () => {
+  describe('hover (interactive)', () => {
+    it('returns true for native interactive tags', () => {
       for (const tag of ['button', 'a', 'input', 'select', 'textarea', 'summary']) {
         const states = inferSupportedNativeStates(makeElement({ tag }))
         expect(states.hover, `hover for <${tag}>`).toBe(true)
-        expect(states.focus, `focus for <${tag}>`).toBe(true)
       }
     })
 
@@ -41,7 +40,6 @@ describe('inferSupportedNativeStates', () => {
       for (const role of interactiveRoles) {
         const states = inferSupportedNativeStates(makeElement({ tag: 'div', role }))
         expect(states.hover, `hover for role=${role}`).toBe(true)
-        expect(states.focus, `focus for role=${role}`).toBe(true)
       }
     })
 
@@ -50,7 +48,6 @@ describe('inferSupportedNativeStates', () => {
       for (const handler of handlers) {
         const states = inferSupportedNativeStates(makeElement({ tag: 'div', eventHandlers: [handler] }))
         expect(states.hover, `hover for ${handler}`).toBe(true)
-        expect(states.focus, `focus for ${handler}`).toBe(true)
       }
     })
 
@@ -71,8 +68,71 @@ describe('inferSupportedNativeStates', () => {
       }
       const states = inferSupportedNativeStates(element)
       expect(states.hover).toBe(true)
+    })
+  })
+
+  describe('focus', () => {
+    it('returns true for native input fields', () => {
+      for (const tag of ['input', 'select', 'textarea']) {
+        expect(inferSupportedNativeStates(makeElement({ tag })).focus, `focus for <${tag}>`).toBe(true)
+      }
+    })
+
+    it('returns true for input-widget roles', () => {
+      const inputWidgetRoles = [
+        'checkbox',
+        'radio',
+        'switch',
+        'slider',
+        'spinbutton',
+        'textbox',
+        'searchbox',
+        'combobox',
+        'listbox',
+      ]
+      for (const role of inputWidgetRoles) {
+        expect(inferSupportedNativeStates(makeElement({ tag: 'div', role })).focus, `focus for role=${role}`).toBe(true)
+      }
+    })
+
+    it('returns false for non-input interactive tags, roles, and event handlers', () => {
+      for (const tag of ['button', 'a', 'summary']) {
+        expect(inferSupportedNativeStates(makeElement({ tag })).focus, `focus for <${tag}>`).toBe(false)
+      }
+      for (const role of ['button', 'link', 'tab', 'menuitem']) {
+        expect(inferSupportedNativeStates(makeElement({ tag: 'div', role })).focus, `focus for role=${role}`).toBe(
+          false,
+        )
+      }
+      for (const eventHandler of ['onClick', 'onFocus', 'onChange']) {
+        expect(
+          inferSupportedNativeStates(makeElement({ tag: 'div', eventHandlers: [eventHandler] })).focus,
+          `focus for ${eventHandler}`,
+        ).toBe(false)
+      }
+    })
+
+    it('returns false for hidden and button-like input types', () => {
+      for (const inputType of ['hidden', 'button', 'submit', 'reset', 'image']) {
+        const states = inferSupportedNativeStates(makeElement({ tag: 'input', attributes: { type: inputType } }))
+        expect(states.focus, `focus for input type=${inputType}`).toBe(false)
+      }
+    })
+
+    it('uses an explicit role instead of the tag implicit semantics', () => {
+      expect(inferSupportedNativeStates(makeElement({ tag: 'input', role: 'button' })).focus).toBe(false)
+      expect(inferSupportedNativeStates(makeElement({ tag: 'button', role: 'checkbox' })).focus).toBe(true)
+    })
+
+    it('allows an authored focus state to opt in a non-input interactive element', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'button' }), { authoredFocus: true })
       expect(states.focus).toBe(true)
     })
+
+    it('ignores an authored focus state on a non-interactive element', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'div' }), { authoredFocus: true })
+      expect(states.focus).toBe(false)
+    })
   })
 
   describe('disabled', () => {
@@ -127,11 +187,19 @@ describe('inferSupportedNativeStates', () => {
   })
 
   describe('tabindex="-1" suppresses focus', () => {
-    it('keeps hover and disabled but suppresses focus on an interactive tag with tabindex="-1"', () => {
-      const states = inferSupportedNativeStates(makeElement({ tag: 'button', attributes: { tabindex: '-1' } }))
+    it('keeps hover and invalid but suppresses default focus on an input with tabindex="-1"', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'input', attributes: { tabindex: '-1' } }))
       expect(states.hover).toBe(true)
       expect(states.focus).toBe(false)
       expect(states.disabled).toBe(true)
+      expect(states.invalid).toBe(true)
+    })
+
+    it('suppresses an explicitly authored focus state on an untabbable element', () => {
+      const states = inferSupportedNativeStates(makeElement({ tag: 'button', attributes: { tabindex: '-1' } }), {
+        authoredFocus: true,
+      })
+      expect(states.focus).toBe(false)
     })
 
     it('does not affect non-interactive elements (no focus to suppress)', () => {

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),
   }