Skip to content

Warn loudly when a <wpd-*> tag is used without being imported#196

Merged
AllTerrainDeveloper merged 1 commit into
trunkfrom
feat-dx-friendly-messages-as-part-of-0.8.3-rework
May 13, 2026
Merged

Warn loudly when a <wpd-*> tag is used without being imported#196
AllTerrainDeveloper merged 1 commit into
trunkfrom
feat-dx-friendly-messages-as-part-of-0.8.3-rework

Conversation

@AllTerrainDeveloper
Copy link
Copy Markdown
Collaborator

@AllTerrainDeveloper AllTerrainDeveloper commented May 13, 2026

Why

A <wpd-*> tag that appears in the DOM without a matching
customElements.define() renders as an inert generic element — no
shadow root, no styles, no behavior, and no error. That silent
failure is the single most common reason a developer's UI "looks
broken for no reason," and the fix (one missing side-effect import)
is invisible from devtools.

This PR turns that silent failure into a loud, actionable
console.error so the next developer who hits it loses minutes, not
hours.

What it does

A new always-on warner watches the document and every open shadow
root. For any unregistered <wpd-*> tag that doesn't get upgraded
within ~2 seconds, it logs one of three messages:

  1. Known tag, never imported — prints the exact
    import '<rel>/ui/components/<name>/<name>'; line to paste.
  2. Typo (e.g. <wpd-buton>) — "Did you mean <wpd-button>?"
    via Levenshtein distance against the canonical tag list.
  3. Unknown tag — points at the registry so the dev can
    discover real names.

Each error attaches the offending element so devtools'
inspect-element jumps straight to it. One warning per tag per page —
not spammy.

How to test

Open OS Settings → Components. You'll see a new
"Missing-import warner — live demo" section. The console shows:

  • A styled yellow banner explaining the next three errors are
    intentional.
  • Three console.error entries, one per branch above.

If you want the demo gone from your fork, delete the section in
src/settings/sections/help.ts — the warner itself stays.

Scope

  • src/ui/components/missing-import-warner.ts — new module.
  • src/desktop.ts — starts the warner before init().
  • src/settings/sections/help.ts — adds the demo section + banner.

No public API changes. No behavior changes for end users.

Open WordPress Playground Preview

@AllTerrainDeveloper
Copy link
Copy Markdown
Collaborator Author

image

@github-actions
Copy link
Copy Markdown

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.


🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

@AllTerrainDeveloper AllTerrainDeveloper merged commit 162353d into trunk May 13, 2026
5 checks passed
@AllTerrainDeveloper AllTerrainDeveloper deleted the feat-dx-friendly-messages-as-part-of-0.8.3-rework branch May 13, 2026 11:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant