@mohamedatia/fly-design-system 2.7.1 → 2.7.3

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

@@ -395,6 +395,40 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
  * routing.
  */
 const FLY_REMOTE_ROUTES = new InjectionToken('FLY_REMOTE_ROUTES');
+/**
+ * Optional injection token a remote provides at its root to declare the shell
+ * mount path prefix (e.g. `'/desktop'`). When set, `FlyRemoteRouter.segments()`
+ * strips this prefix from `window.location.pathname` before matching routes.
+ *
+ * **Why this is needed:** In embedded mode the remote is loaded via
+ * `NgComponentOutlet` inside the shell SPA. The shell's own Angular route may
+ * leave `window.location.pathname` as `/desktop` (or any shell-level path).
+ * Without stripping that prefix, `segments()` returns `['desktop']` which
+ * matches none of the remote's Circles-internal routes (e.g. `''`, `'signals'`,
+ * `'signals/:id'`), so `<fly-remote-router-outlet>` renders nothing.
+ *
+ * **Default behaviour (token absent):** `FlyRemoteRouter` initialises `_url`
+ * to `'/'` in embedded mode, completely ignoring `window.location.pathname`.
+ * This is safe because the shell does not push the remote's logical URL into
+ * browser history — only `navigate()` / `navigateByUrl()` calls do.
+ *
+ * **Usage in a remote root component:**
+ * ```ts
+ * providers: [
+ *   FlyRemoteRouter,
+ *   { provide: FLY_REMOTE_ROUTES, useValue: MY_ROUTES },
+ *   { provide: FLY_REMOTE_BASE_PATH, useValue: '/desktop' },
+ * ]
+ * ```
+ *
+ * With `basePath = '/desktop'` and `window.location.pathname = '/desktop'`,
+ * the stripped URL is `'/'` → `segments() = []` → matches the `''` default
+ * route. With pathname `'/desktop/signals/abc'`, segments become
+ * `['signals', 'abc']` → matches `'signals/:id'`.
+ *
+ * Available since design-system **2.7.2**.
+ */
+const FLY_REMOTE_BASE_PATH = new InjectionToken('FLY_REMOTE_BASE_PATH');
 /**
  * Match a route's path pattern against URL segments. Returns the captured params
  * map on a successful match, or `null` if the pattern can't match. Empty path
@@ -489,6 +523,15 @@ class FlyRemoteRouter {
      * driving its own switch/template — `matchedRoute` stays `null`.
      */
     routes = inject(FLY_REMOTE_ROUTES, { optional: true }) ?? [];
+    /**
+     * Shell mount path prefix to strip from `window.location.pathname` when
+     * deriving the initial URL in embedded mode. See `FLY_REMOTE_BASE_PATH` docs.
+     *
+     * When absent (the common case), the embedded router initialises `_url` to
+     * `'/'` and ignores `window.location.pathname` entirely — correct because the
+     * shell SPA never encodes the remote's logical route into the browser URL.
+     */
+    basePath = inject(FLY_REMOTE_BASE_PATH, { optional: true }) ?? null;
     /**
      * True when this remote is rendered inside the FlyOS desktop shell.
      *
@@ -565,9 +608,16 @@ class FlyRemoteRouter {
             });
         }
         else if (this.isEmbedded) {
-            // Embedded: seed from current browser location on initial load.
+            // Embedded: the shell SPA keeps its own route in window.location.pathname
+            // (e.g. '/desktop') which is meaningless for the remote's route table.
+            // Default: initialise to '/' so the remote's empty-path default route
+            // matches on first render. When FLY_REMOTE_BASE_PATH is provided, strip
+            // it from pathname first — useful if the shell does push a remote-aware
+            // URL (e.g. '/desktop/signals/abc' with basePath '/desktop').
             if (typeof window !== 'undefined') {
-                this._url.set(window.location.pathname || '/');
+                const rawPath = window.location.pathname || '/';
+                const initialUrl = this._resolveEmbeddedInitialUrl(rawPath);
+                this._url.set(initialUrl);
                 // Listen for browser back/forward so segments() stays in sync with
                 // history entries pushed by navigate() / navigateByUrl().
                 const onPopState = (event) => {
@@ -623,6 +673,34 @@ class FlyRemoteRouter {
             history.back();
         }
     }
+    /**
+     * Resolve the logical URL to seed `_url` from on embedded initial load.
+     *
+     * - No basePath: always return `'/'`. The shell's SPA path (e.g. `/desktop`)
+     *   is irrelevant to the remote — `navigate()` is the only thing that should
+     *   move the remote's URL.
+     * - basePath provided: strip it from `rawPath`. If rawPath starts with the
+     *   basePath, the remainder becomes the seed URL (normalised to start with
+     *   `'/'`). If it doesn't match (e.g. shell changed its own route), fall back
+     *   to `'/'` rather than surfacing shell-specific segments to the remote's
+     *   route table.
+     */
+    _resolveEmbeddedInitialUrl(rawPath) {
+        if (!this.basePath) {
+            // Default: ignore the shell's pathname, start at remote root.
+            return '/';
+        }
+        const base = this.basePath.endsWith('/') ? this.basePath.slice(0, -1) : this.basePath;
+        if (rawPath === base || rawPath === base + '/') {
+            return '/';
+        }
+        if (rawPath.startsWith(base + '/')) {
+            const remainder = rawPath.slice(base.length);
+            return remainder.startsWith('/') ? remainder : '/' + remainder;
+        }
+        // Shell path doesn't begin with our basePath — fall through to root.
+        return '/';
+    }
     /**
      * In embedded mode: push a real browser history entry (so back/forward work)
      * and update the internal signal synchronously.
@@ -671,9 +749,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
  *   3. Parses the HTML with DOMParser to extract the first
  *      `<link rel="stylesheet">` — the hashed production stylesheet
  *      (e.g. `styles-ABC123.css`). This is Strategy (b): index.html discovery.
- *   4. Injects `<link rel="stylesheet" data-fly-app="<appId>">` into
- *      `document.head`. Idempotent: if an identical href is already present,
- *      the call is a no-op. If the href differs (hot upgrade), it is replaced.
+ *   4. Injects an inline `<style data-fly-app="<appId>">` block containing
+ *      `@layer remote { @import url("..."); }` into `document.head`.
+ *      Idempotent: if a `<style data-fly-app="appId">` with the same href
+ *      is already present, the call is a no-op. If the href differs (hot
+ *      upgrade), the existing element is replaced.
  *
  * Why strategy (b)?
  * -----------------
@@ -683,6 +763,33 @@ 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`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Layer order declaration
+ * -----------------------
+ * A one-time `<style data-fly-layers>` element is prepended to `<head>` the first
+ * time any remote style is loaded. It establishes the canonical layer order:
+ *   reset → designsystem → shell → remote → overrides
+ * This guarantees that even if individual `@layer` blocks are injected in any
+ * order at runtime, the cascade priority is always deterministic.
+ *
  * Unload decision
  * ---------------
  * `unloadRemoteStyles` is exported for symmetry but should NOT be called on
@@ -696,7 +803,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
  * - CORS: the remote's dev/prod server must serve `index.html` with a
  *   permissive `Access-Control-Allow-Origin` header (or be same-origin via
  *   the YARP gateway). The fetch uses `credentials: 'omit'` to avoid
- *   credential-carrying preflights.
+ *   credential-carrying preflights. The CSS file itself must also be CORS-
+ *   accessible since `@import` inside a `<style>` is subject to CORS checks.
  * - Race on rapid mount/unmount: if `loadRemoteStyles` is called a second time
  *   for the same appId while the first fetch is still in-flight, the second
  *   call joins the same in-flight Promise (idempotency guard at fetch level).
@@ -709,6 +817,35 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.5", ngImpor
 const _resolvedHref = new Map();
 /** In-flight fetch promises keyed by appId — prevents duplicate fetches. */
 const _inFlight = new Map();
+/**
+ * Whether the canonical layer-order declaration has already been injected.
+ * Module-level so it survives across multiple `loadRemoteStyles` calls within
+ * the same shell session but is reset on a full page reload.
+ */
+let _layersDeclared = false;
+/**
+ * Injects a single `<style data-fly-layers>` element at the top of `<head>`
+ * that establishes the canonical cascade-layer priority order for the shell:
+ *
+ *   reset → designsystem → shell → remote → overrides
+ *
+ * Any subsequent `@layer X { … }` block lands in the already-established slot
+ * regardless of injection order, so late-arriving remote stylesheets never
+ * "win" over shell or override rules. Idempotent — runs at most once per page.
+ */
+function _ensureLayerOrder() {
+    if (_layersDeclared)
+        return;
+    _layersDeclared = true;
+    // Guard against duplicate elements in the DOM (e.g. hot-module-reload edge cases).
+    if (document.head.querySelector('style[data-fly-layers]'))
+        return;
+    const style = document.createElement('style');
+    style.setAttribute('data-fly-layers', '');
+    style.textContent = '@layer reset, designsystem, shell, remote, overrides;';
+    // Prepend so this always precedes any other layer-bearing <style> blocks.
+    document.head.insertBefore(style, document.head.firstChild);
+}
 /**
  * Discovers the hashed stylesheet href from the remote's `index.html`.
  * Returns `null` if no stylesheet `<link>` is found or the fetch fails.
@@ -752,13 +889,24 @@ async function _discoverStylesheetHref(remoteBaseUrl) {
  *                        or `http://localhost:7202`. Must NOT include `/remoteEntry.json`.
  *
  * The call is idempotent:
- *  - If a `<link data-fly-app="appId">` with the same href already exists → no-op.
- *  - If the href differs (hot upgrade) → existing link is replaced.
+ *  - If a `<style data-fly-app="appId">` whose content references the same href
+ *    already exists → no-op.
+ *  - If the href differs (hot upgrade) → existing element is replaced.
  *  - If no stylesheet is found in `index.html` → no-op (logged as a warning).
+ *
+ * Injection shape:
+ *   <style data-fly-app="<appId>" data-fly-href="<href>">
+ *     @layer remote { @import url("<href>"); }
+ *   </style>
+ *
+ * The `data-fly-href` attribute stores the discovered href separately from the
+ * style content so idempotency checks can compare the URL without parsing CSS.
  */
 async function loadRemoteStyles(appId, remoteBaseUrl) {
     if (typeof document === 'undefined')
         return; // SSR guard
+    // Ensure the canonical layer order is declared before any remote layer is injected.
+    _ensureLayerOrder();
     // Kick off or join an in-flight fetch for this appId.
     let fetchPromise = _inFlight.get(appId);
     if (!fetchPromise) {
@@ -778,19 +926,21 @@ async function loadRemoteStyles(appId, remoteBaseUrl) {
         console.warn(`[FlyOS] loadRemoteStyles: no stylesheet found in ${remoteBaseUrl}/index.html for appId="${appId}"`);
         return;
     }
-    const existing = document.head.querySelector(`link[data-fly-app="${CSS.escape(appId)}"]`);
+    const selector = `style[data-fly-app="${CSS.escape(appId)}"]`;
+    const existing = document.head.querySelector(selector);
     if (existing) {
-        if (existing.getAttribute('href') === href)
+        if (existing.getAttribute('data-fly-href') === href)
             return; // identical — no-op
-        // Hot upgrade: replace href.
-        existing.setAttribute('href', href);
-        return;
-    }
-    const link = document.createElement('link');
-    link.rel = 'stylesheet';
-    link.setAttribute('data-fly-app', appId);
-    link.href = href;
-    document.head.appendChild(link);
+        // 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.
+    const style = document.createElement('style');
+    style.setAttribute('data-fly-app', appId);
+    style.setAttribute('data-fly-href', href);
+    style.textContent = `@layer remote { @import url("${href}"); }`;
+    document.head.appendChild(style);
 }
 /**
  * Removes the injected stylesheet for `appId` from `document.head`.
@@ -802,8 +952,8 @@ async function loadRemoteStyles(appId, remoteBaseUrl) {
 function unloadRemoteStyles(appId) {
     if (typeof document === 'undefined')
         return; // SSR guard
-    const link = document.head.querySelector(`link[data-fly-app="${CSS.escape(appId)}"]`);
-    link?.parentNode?.removeChild(link);
+    const style = document.head.querySelector(`style[data-fly-app="${CSS.escape(appId)}"]`);
+    style?.parentNode?.removeChild(style);
     _resolvedHref.delete(appId);
 }
 
@@ -4219,5 +4369,5 @@ const AUDIENCE_ERROR_CODES = {
  * Generated bundle index. Do not edit.
  */
 
-export { AGENT_DRAG_MIME, AGENT_PAYLOAD_VERSION, AUDIENCE_ERROR_CODES, AUDIENCE_LIMITS, AUDIENCE_PRESETS, AUDIENCE_TERM_KINDS, AgentCommandRegistry, AgentDropRegistry, AgentPayloadOversizeError, AudienceBuilderComponent, AuthService, ContextMenuComponent, DEFAULT_AGENT_PAYLOAD_LIMITS, DEFAULT_FLY_THEME_MODE, DialogResult, FLY_LOCALE_CATALOG, FLY_REMOTE_ROUTES, FLY_THEME_MODE_IDS, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyRemoteRouter, FlyRemoteRouterOutletComponent, FlyThemeService, I18nService, LAUNCH_CONTEXT, MessageBoxButtons, MessageBoxComponent, MessageBoxIcon, MessageBoxService, MockAuthService, RTL_LOCALE_SET, SHARE_ORG_CHART_SYSTEM_KEY_APPS, SHARE_ORG_CHART_SYSTEM_KEY_DEFAULT, SHARE_PANEL_DEFAULT_FILE_LEVELS, SharePanelComponent, StandaloneWindowManagerService, TranslatePipe, WINDOW_DATA, WindowManagerService, findLocaleByDialect, findLocaleByPrefix, isRtlLocale, isRtlLocaleEntry, loadRemoteStyles, matchFlyRoutePattern, normalizeFlyTheme, trimAgentPayload, trimAgentString, unloadRemoteStyles, utf8ByteLength, validateAgentPayload };
+export { AGENT_DRAG_MIME, AGENT_PAYLOAD_VERSION, AUDIENCE_ERROR_CODES, AUDIENCE_LIMITS, AUDIENCE_PRESETS, AUDIENCE_TERM_KINDS, AgentCommandRegistry, AgentDropRegistry, AgentPayloadOversizeError, AudienceBuilderComponent, AuthService, ContextMenuComponent, DEFAULT_AGENT_PAYLOAD_LIMITS, DEFAULT_FLY_THEME_MODE, DialogResult, FLY_LOCALE_CATALOG, FLY_REMOTE_BASE_PATH, FLY_REMOTE_ROUTES, FLY_THEME_MODE_IDS, FlyAgentDraggableDirective, FlyBlockUiComponent, FlyFileUploadComponent, FlyImageUploadComponent, FlyRemoteRouter, FlyRemoteRouterOutletComponent, FlyThemeService, I18nService, LAUNCH_CONTEXT, MessageBoxButtons, MessageBoxComponent, MessageBoxIcon, MessageBoxService, MockAuthService, RTL_LOCALE_SET, SHARE_ORG_CHART_SYSTEM_KEY_APPS, SHARE_ORG_CHART_SYSTEM_KEY_DEFAULT, SHARE_PANEL_DEFAULT_FILE_LEVELS, SharePanelComponent, StandaloneWindowManagerService, TranslatePipe, WINDOW_DATA, WindowManagerService, findLocaleByDialect, findLocaleByPrefix, isRtlLocale, isRtlLocaleEntry, loadRemoteStyles, matchFlyRoutePattern, normalizeFlyTheme, trimAgentPayload, trimAgentString, unloadRemoteStyles, utf8ByteLength, validateAgentPayload };
 //# sourceMappingURL=mohamedatia-fly-design-system.mjs.map