[feat]: support non-element `ReactiveControllerHost` in pfe-core controllers
@bennypowers 已经在做这个了。
开始于 2026年10月22日。
评估
这个 Issue 还没有评估数据。
描述
Summary
Many @patternfly/pfe-core controllers assume their ReactiveControllerHost is an element. @lit/react's useController (@lit/react/use-controller.js, v1.0.8) supplies a plain object host, so several controllers cannot be reused from React components today. This issue tracks the refactor needed to make them host-agnostic, plus the breaking changes and temporary workarounds.
Motivation
We want to share controller logic between Lit elements and React components instead of reimplementing keyboard, ARIA, and overflow behavior in React. .claude/ADVICE.md already states the intent:
Bear in mind we may need to make all of these controllers work with
ReactiveControllerHostthat isn't an element. (PFE PR #2570)
Host contract
useController(React, host => new SomeController(host, options)) creates this host:
addController,removeControllerrequestUpdate()triggers a React state updateupdateCompleteresolves, but is not tied to a React commithostConnected()runs from theuseStateinitializer, before refs attachhostUpdate()runs during render, before commithostUpdated()runs in a layout effect, after commithostDisconnected()runs on unmount
It has no isConnected, localName, querySelector, getRootNode, children, renderRoot, or shadowRoot.
Consequences for controllers:
- DOM access must be lazy, through a getter that reads a ref at call time.
- Setup must not happen in the constructor or
hostConnected, since refs are null then. - Element resolution must be retried in
hostUpdated, not onlyhostConnected. useControlleritself is not SSR-safe in v1.0.8 because it callshostConnected()during render. Controllers still needisServerguards.
Inventory
Usable as-is
| Controller | Notes |
|---|---|
Logger |
Falls back to host.constructor.name (logger.ts:9-13) |
TimestampController |
Pure Intl logic, only calls addController (timestamp-controller.ts:68) |
Usable with options, needs hardening
| Controller | Required options | Change needed |
|---|---|---|
ATFocusController |
getItemsContainer, getOrientation |
Container falls back to host and silently becomes null (at-focus-controller.ts:150-153). Warn or throw when a non-element host has no container. Re-resolve in hostUpdated. |
ActivedescendantController |
getActiveDescendantContainer, getItemsContainer, controls |
Same container handling. initItems() runs in the constructor (activedescendant-controller.ts:247). |
ListboxController |
getItemsContainer |
Already throws clearly (listbox-controller.ts:235-241). Listener setup depends on hostConnected, which runs before refs attach, so container resolution needs a retry in hostUpdated. |
RovingTabindexController |
getItemsContainer, getOrientation |
Attaches focusin listeners in the constructor (roving-tabindex-controller.ts:75-97), before refs exist. Move to hostConnected, retry in hostUpdated. |
TabsAriaController |
getHTMLElement |
Throws in the constructor when the getter returns null (tabs-aria-controller.ts:59-69), which is always the case during the first React render. Resolve lazily and initialize in hostConnected/hostUpdated; remove the slotchange listener in hostDisconnected for StrictMode idempotency. |
FloatingDOMController |
invoker, content, arrow refs |
Defaults invoker to host as LitElement (floating-dom-controller.ts:91). Make it required or lazy for non-element hosts. |
Needs a mechanical refactor
Pattern:
constructor(
public host: ReactiveControllerHost,
private options: { getElement(): HTMLElement | null },
) {}
#element() {
return this.options.getElement()
?? (this.host instanceof HTMLElement ? this.host : null);
}
hostConnected() {
const el = this.#element();
if (!el) return;
// observe / listen
}
hostUpdated() {
// re-resolve if the ref changed, then read DOM
}
| Controller | Public host type | Current assumption |
|---|---|---|
OverflowController |
Yes, public host: ReactiveElement |
Observes host and checks host.isConnected (overflow-controller.ts:65-78, 140-142) |
ScrollSpyController |
No, private host |
Uses host.querySelectorAll and host.getRootNode (scroll-spy-controller.ts:95, 131, 140, 228) |
CssVariableController |
Yes, public host: ReactiveElement |
Calls getComputedStyle(host) (css-variable-controller.ts:6, 21) |
LightDOMController |
No, private host |
Binds the initializer to host, observes host, reads host.children and host.textContent (light-dom-controller.ts:16, 44, 58-61) |
PerfController |
No, private host |
Reads host.id and host.localName in the constructor (perf-controller.ts:10-19) |
A private getter is enough for the DOM work in all five. The public type change is only unavoidable for OverflowController and CssVariableController, because host is a public property. ScrollSpy, LightDOM, and Perf can widen their constructor parameter and private host type without a public type break, since the emitted declaration is already private host;.
Needs redesign
| Controller | Blocker |
|---|---|
InternalsController |
Instance registry is already WeakMap<HTMLElement, InternalsController>, but attachInternals() requires a custom element and globalThis._elementInternals must be keyed by that element for aXe (internals-controller.ts:75, 255-269, 291). A plain React host object cannot attach internals, and getHTMLElement() only works when the ref is a form-associated custom element. Existing element callers are unaffected; the break is limited to widening InternalsHost and of(). |
ComboboxController |
Host typed ReactiveControllerHost & HTMLElement and passed to ListboxController.of(host, ...) (combobox-controller.ts:332-357). Focusout checks host instanceof Node && host.contains(target) (:218), which is false for a plain host, so the listbox never closes. InternalsController.getLabels(this.host) (:468) targets the wrong object. A private root-element getter plus a controller-keyed focusout set covers the runtime behavior; only the public host and of() types need to widen. |
Keep element-only
| Controller | Reason |
|---|---|
SlotController |
Shadow DOM slots and host.shadowRoot (slot-controller.ts:157, 179, 183) |
StyleController |
Adopted stylesheets on host.renderRoot (style-controller.ts:24, 33) |
PropertyObserverController |
Uses ReactiveElement.getPropertyOptions, hasUpdated, and patches connectedCallback (property-observer-controller.ts:63-85). React should use prop diffing in a hook instead. |
Private getter sufficiency
A private #element() or #container() getter that resolves from an optional callback and falls back to host instanceof HTMLElement is enough for most controllers. It does not, by itself, protect a public host property type.
| Controller | Private getter enough? | Remaining public change |
|---|---|---|
Logger, TimestampController |
n/a | None |
ATFocusController |
Yes | None, host is already ReactiveControllerHost |
ActivedescendantController |
Yes | None |
RovingTabindexController |
Yes | None |
ListboxController |
Yes | None |
TabsAriaController |
Yes | None |
FloatingDOMController |
Yes | None |
LightDOMController |
Yes, but bind the initializer to the resolved element | None |
ScrollSpyController |
Yes | None |
PerfController |
Yes, but defer performance.mark until the element exists |
None |
OverflowController |
Yes for observers | Public host: ReactiveElement must widen or use an unsound cast |
CssVariableController |
Yes for getComputedStyle |
Public host: ReactiveElement must widen or use an unsound cast |
ComboboxController |
Yes, plus a controller-keyed focusout set and a root-element getter | Public host and of() types widen |
InternalsController |
No | Element identity and attachInternals require a real custom element ref |
PropertyObserverController, SlotController, StyleController |
No | Element-only |
Lifecycle registration
useController only drives controllers registered with host.addController(this). Several controllers never register:
CssVariableControllerdoes not calladdController, and it has no in-repo callers that register it, sohostConnectednever runs on its behalf.ATFocusControllerand its subclasses do not register, and rely on constructor side effects for initial setup.PropertyObserverControllerdoes not register itself, but the@observedand@observesdecorators do add it to an element host.
Adding registration is source-compatible, but it changes behavior for Lit elements because hostConnected and hostDisconnected will start running. It also exposes an existing reconnect bug: ATFocusController.hostDisconnected removes the keydown listener, while hostConnected/hostUpdate do not re-add it because itemsContainerElement is still set. Registration must come with reconnect handling, and the StrictMode tests below must cover it.
Proposed phases
- Non-breaking hardening: lazy element resolution and
hostUpdatedretries inATFocus,Activedescendant,Listbox,RovingTabindex,TabsAria,FloatingDOM. - Mechanical refactor: add private element getters and widen constructor parameters in
Overflow,ScrollSpy,CssVariable,LightDOM,Perf. OnlyOverflowandCssVariablerequire a publichosttype decision. - Redesign with overloads:
InternalsControllerandComboboxController, preserving element behavior while allowing an element ref from React. - Lifecycle registration: add
addControllerwhere missing, with reconnect handling forATFocusand subclasses. - Tests: required React coverage for every controller touched, using real
useControllerhooks and element refs. See the testing requirement below.
React testing requirement
React integration tests are a merge requirement for every controller changed under this issue. They are not a follow-up, a nice-to-have, or something that can be waived because the Lit tests pass.
Each controller refactor must ship tests that:
- Build a hook with
useController(React, host => new SomeController(host, options)). - Render a React component that attaches element refs and passes them through the controller options, for example
getItemsContainer: () => listRef.current. - Assert that the controller works after refs attach, not only when constructed with a pre-existing element.
- Cover the behavior the controller owns: keyboard navigation and orientation, ARIA attributes on the correct nodes, observers and listeners, and cleanup on unmount.
- Exercise React StrictMode double-mount where the controller attaches observers or listeners.
- Verify that a controller reconnects after
hostDisconnected, including re-adding listeners and observers. - Fail if the controller only works with an
HTMLElementcast or requires the host to be an element.
A local ElementHost test double is useful for unit tests, but it does not replace real React tests. A PR that changes a controller without React coverage is incomplete.
This repo does not currently have React test tooling, so the first PR will need to add it, for example @testing-library/react plus a DOM environment such as jsdom or happy-dom, wired into the existing test runner.
Potential breaking changes and workarounds
| Change | Risk | Workaround |
|---|---|---|
public host widens from ReactiveElement or HTMLElement to ReactiveControllerHost |
Only affects OverflowController, CssVariableController, ComboboxController, and InternalsController; consumers who use controller.host as an element lose methods. ATFocus, Activedescendant, RovingTabindex, and Listbox already use ReactiveControllerHost. |
Add a typed element getter and keep host for controller plumbing; document the migration. Do not keep the old type with an unsound cast. |
Container setup moves from constructors to hostConnected |
Behavior change, not a type break. Code that constructed a controller and relied on listeners attaching immediately stops working. | Lit elements are unaffected because addController drives hostConnected; manual users call hostConnected() explicitly |
| Non-element hosts without element getters now throw or warn where they previously no-opped | Tests or apps relying on silent degradation may fail | Keep the implicit host instanceof HTMLElement fallback; only throw when the host is not an element and no getter exists |
TabsAriaController constructor no longer throws when the element is missing |
Early failure moves to first update | Expose an explicit assertElement() or keep a getHTMLElement() check in the consumer |
getHTMLElement is renamed to getElement or getTabList |
Breaks existing options objects. This rename is not required for React support. | Keep the existing name, or keep it as a deprecated alias for at least one major release |
InternalsController widens InternalsHost and of() to accept a plain host |
The instance registry is already element-keyed, and existing element callers keep working. The break is limited to the public type and to globalThis._elementInternals needing the element rather than the host. |
Add an overload for plain hosts with a required getHTMLElement() option; keep the element overload unchanged |
ComboboxController uses an element ref instead of host.contains |
Internal behavior changes in focusout handling; this is not a public API break. | Verify with existing combobox tests and add a React regression test |
Controllers start calling addController |
Lit elements begin receiving hostConnected and hostDisconnected, which can expose reconnect bugs |
Pair registration with reconnect handling, especially in ATFocusController, and cover it with StrictMode tests |
PropertyObserverController left unchanged |
No React support | Implement a separate hook for prop diffing; do not rewrite the controller |
Temporary workarounds before this lands
-
For controllers that already accept element getters (
ATFocus,Activedescendant,Listbox,RovingTabindex,TabsAria,FloatingDOM), gate controller creation until a ref exists, or call arefresh()in the ref callback so a render occurs after the element is attached. -
For element-bound controllers, create the controller inside a
useEffectwith a minimal host adapter, then callhostConnected(),hostUpdated(), andhostDisconnected()manually:class ElementHost implements ReactiveControllerHost { updateComplete = Promise.resolve(); #controllers = new Set<ReactiveController>(); constructor(public element: HTMLElement, private onChange: () => void) {} addController(c: ReactiveController) { this.#controllers.add(c); } removeController(c: ReactiveController) { this.#controllers.delete(c); } requestUpdate() { this.onChange(); } } -
When a React-native wrapper is not required, use
@lit/react'screateComponentaround the actual custom element instead of reusing element-bound controllers.
Related
- #3165 (
aria-orientationsupport inTabsAriaController) .claude/ADVICE.md, "Design controllers forReactiveControllerHost, not just elements"
Jira Issue: FELT-6313
- 主要语言
- TypeScript
- 星标
- 397
- 派生
- 109
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
patternfly/patternfly-elements 的其他 Issue
-
accessibility feature priority: low
难度 4/5 1-2 天 新手友好度 57/100
patternfly/patternfly-elements#3165 · 3 条评论 ·
-
[bug] ssr-shims.js uses deprecated globalThis.litSsrCallConnectedCallback可能已有人在做 @zeroedin 于 106 天前认领。 未关闭bug
patternfly/patternfly-elements#3158 · 已指派 1 人 ·
-
chore: evaluate removing isolatedDeclarations from tsconfig可能重新可做 @bennypowers 于 196 天前认领,目前没有进行中的 PR。 未关闭
patternfly/patternfly-elements#3136 · 1 条评论 · 已指派 1 人 ·
-
chore: update docs scaffolding for v6 elements可能重新可做 @zeroedin 于 196 天前认领,目前没有进行中的 PR。 未关闭docs
patternfly/patternfly-elements#3131 · 已指派 1 人 ·
-
难度 4/5 3-5 天 新手友好度 55/100
patternfly/patternfly-elements#3122 ·
查看 patternfly/patternfly-elements 的全部 Issue
相似的 Issue
-
[Site] Active section detection should respect scroll-margin-top可能已有人在做 关联的 PR 仍在进行中或已合并。 未关闭area/web reproduced type/bug
难度 2/5 1-3 小时 新手友好度 65/100
anomalyco/opencode#65384 · 1 条评论 ·
维护者通常 1 天内回复
-
bug
难度 2/5 1-3 小时 新手友好度 78/100
swc-project/swc-ai-issues#1001 ·
-
check:passed streams:add
难度 1/5 1 小时以内 新手友好度 62/100
维护者通常 1 天内回复
-
fix(table): CollapseColumn uses wrong caret icon for expandable row toggle可能已有人在做 @redhat-chai-bot 今天认领。 未关闭
难度 1/5 1 小时以内 新手友好度 85/100
patternfly/patternfly-react#12727 ·
维护者通常 1 天内回复
-
CLI OAuth login fails behind an authenticating proxy: GET /api/v1/user omits Proxy-Authorization未关闭
难度 1/5 1 小时以内 新手友好度 85/100
lightdash/lightdash#33086 · 1 条评论 ·
维护者通常 1 天内回复