Skip to content

docs: stop hiding snippet fallback prematurely (:defined race) #260

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adamziel merged 1 commit into from
May 3, 2026
+17 −6
Merged

docs: stop hiding snippet fallback prematurely (:defined race) #260

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion bin/build-reference.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
from _load_catalog import load_components_rich

DOCS = os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'docs', 'reference')
ASSET_VERSION = '20260503-script-unescape'
ASSET_VERSION = '20260503-fallback-explicit-hide'


PAGE_HEAD = '''<!doctype html>
Expand Down
9 changes: 9 additions & 0 deletions docs/assets/page.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,15 @@
const code = root.querySelector('pre code');
if (!code) return;

// Shadow DOM has rendered content. Hide the static fallback now —
// not via a CSS `:defined` rule, which fires too early (the moment
// customElements.define() runs, before shadow-DOM render). See
// .snippet-fallback rules in style.css for context.
const fallback = el.querySelector(':scope > .snippet-fallback');
if (fallback) {
fallback.style.display = 'none';
}

// HTML emitted by build-reference.py escapes "</script" inside the
// <script type="application/x-php"> wrapper as "<\/script" so the
// outer tag isn't closed prematurely. The browser preserves that
Expand Down
12 changes: 7 additions & 5 deletions docs/assets/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -483,10 +483,13 @@ p code, li code, td code {

php-snippet { display: block; margin: 1rem 0 1.75rem; }

/* Static fallback: shows the snippet code if the cross-origin Playground
custom element fails to register (CSP block, slow network, adblocker,
no-JS reader). Hidden as soon as <php-snippet> is defined so the
interactive widget owns the screen when it boots. */
/* Static fallback: shows the snippet code until the cross-origin Playground
custom element registers AND populates its shadow DOM. page.js hides
this element explicitly once shadow-DOM render is confirmed in
patchSnippet — we do not use a CSS `:defined` rule because that fires
the instant `customElements.define()` runs, before the shadow DOM has
any content. If the cross-origin module never loads (CSP, adblock,
slow network, no-JS), this fallback stays visible. */
.snippet-fallback {
margin: 0;
padding: 0.9rem;
Expand All @@ -499,7 +502,6 @@ php-snippet { display: block; margin: 1rem 0 1.75rem; }
line-height: 1.55;
}
.snippet-fallback code { color: inherit; background: none; padding: 0; }
php-snippet:defined .snippet-fallback { display: none; }

.code-example {
margin: 1rem 0 1.75rem;
Expand Down
Loading