@mohamedatia/fly-design-system 2.7.3 → 2.7.4

package/fesm2022/mohamedatia-fly-design-system.mjs

@@ -763,24 +763,25 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
  * (c) `stylesUrl` in manifest/remoteEntry.json — cleanest long-term; requires
  *     protocol change to every remote's CI pipeline (out of scope for Wave A1).
  *
- * CSS Cascade Layer — Option A (`@import` inside inline `<style>`)
- * ----------------------------------------------------------------
- * Remote stylesheets are injected inside `@layer remote { @import url("..."); }`
- * rather than as bare `<link rel="stylesheet">`. This keeps remote styles in a
- * named cascade layer so the shell can reliably override them via `@layer overrides`.
+ * CSS Cascade Layer — `@import url("...") layer(remote)`
+ * --------------------------------------------------------
+ * Remote stylesheets are injected via `@import url("…") layer(remote)` (CSS
+ * Cascade Level 5). This keeps remote styles in a named cascade layer so the
+ * shell can reliably override them via `@layer overrides`.
  *
- * Option A was chosen over:
- *   - Option B (fetch+inline): relative `url(...)` paths inside the remote CSS
- *     would resolve against the shell origin instead of the remote origin,
- *     breaking fonts and images. Dealbreaker without a full URL-rewrite pass.
- *   - Option C (`<link layer="remote">`): the `layer` attribute on `<link>` is
- *     not yet shipped in Firefox (as of 2025-05). Chromium 99+ and Safari 16.4+
- *     support it, but Firefox is still behind, making it non-portable today.
+ * The block-form `@layer remote { @import url("…"); }` is INVALID CSS — the
+ * spec forbids `@import` inside any block at-rule. Browsers silently drop such
+ * rules, causing remote stylesheets to never load. The correct syntax is the
+ * `layer()` modifier on a top-level `@import`.
  *
- * Trade-off of Option A: `@import` inside `@layer` delays style application until
- * the remote stylesheet is fetched (same as a plain `<link>`, effectively). Modern
- * engines schedule it as a discoverable resource from the inline `<style>` element.
- * The performance characteristic is equivalent to the old `<link>` approach.
+ * Browser support: Chrome 99+, Firefox 97+, Safari 15.4+ — all current engines.
+ *
+ * Alternative approaches rejected:
+ *   - Fetch+inline: relative `url(...)` paths inside the remote CSS would
+ *     resolve against the shell origin instead of the remote origin, breaking
+ *     fonts and images. Dealbreaker without a full URL-rewrite pass.
+ *   - `<link layer="remote">`: the `layer` attribute on `<link>` is not yet
+ *     shipped in Firefox (as of 2025-05). Non-portable.
  *
  * Layer order declaration
  * -----------------------
@@ -896,7 +897,7 @@ async function _discoverStylesheetHref(remoteBaseUrl) {
  *
  * Injection shape:
  *   <style data-fly-app="<appId>" data-fly-href="<href>">
- *     @layer remote { @import url("<href>"); }
+ *     @import url("<href>") layer(remote);
  *   </style>
  *
  * The `data-fly-href` attribute stores the discovered href separately from the
@@ -934,12 +935,14 @@ async function loadRemoteStyles(appId, remoteBaseUrl) {
         // Hot upgrade: replace the entire element so the @import URL updates atomically.
         existing.remove();
     }
-    // Option A: inline <style> with @layer remote { @import url("..."); }.
-    // See module JSDoc for the rationale over Options B and C.
+    // CSS Cascade Level 5: `@import url("…") layer(remote)` is the only valid
+    // way to place an @import inside a named cascade layer. Block-form
+    // `@layer remote { @import … }` is invalid and silently dropped by browsers.
+    // See module JSDoc for full rationale.
     const style = document.createElement('style');
     style.setAttribute('data-fly-app', appId);
     style.setAttribute('data-fly-href', href);
-    style.textContent = `@layer remote { @import url("${href}"); }`;
+    style.textContent = `@import url("${href}") layer(remote);`;
     document.head.appendChild(style);
 }
 /**