@myop/sdk 0.4.0-beta.4 → 0.4.0-beta.6

package/README.md

@@ -328,6 +328,19 @@ const flow = await CloudRepository.Main.fetchFlow('flow-id');
 const isLoaded = CloudRepository.Main.isPreloaded('component-id');
 ```
 
+### Runtime tags (`ui:*`)
+
+Read a component's `ui:`-prefixed tags client-side, in the same response that loads it:
+
+```typescript
+import { preloadComponents, getComponentTags } from '@myop/sdk/helpers';
+
+await preloadComponents(['component-id']);
+getComponentTags('component-id'); // ['ui:beta']  — also on a mounted component as component.uiTags
+```
+
+Only tags starting with `ui:` reach the browser. See [Runtime Tags](https://docs.myop.dev/docs/learn/ui-tags/).
+
 ### Host SDK
 
 ```typescript

package/dist/bundled-declarations.d.ts

@@ -370,6 +370,11 @@ declare module "@myop/sdk/common" {
         id: string;
         name: string;
         description: string;
+        /**
+         * The component's runtime tags: only tags named `ui:...` (e.g. `ui:beta`), as set in the
+         * dashboard. Every other tag stays private on the server. Empty when there are none.
+         */
+        uiTags?: string[];
         props: IPropConfig[];
         refs: IRefConfig[];
         skins: ISkinConfig[];
@@ -1225,6 +1230,8 @@ declare module "@myop/sdk/host/components/IMyopComponent" {
         markedForDisposed: boolean;
         setInitiated: () => void;
         componentDefinition: IComponentDefinitionConfig;
+        /** Runtime tags: only tags named `ui:...` (e.g. `ui:beta`). `[]` when there are none. */
+        readonly uiTags: string[];
         container: HTMLElement;
         element?: HTMLElement;
         send: (msg: BaseMyopMessage) => CleanupHandler;
@@ -1268,6 +1275,7 @@ declare module "@myop/sdk/host/components/IMyopComponent" {
         messageHandlers: Record<string, messageHandler<any>[]>;
         element?: HTMLElement;
         protected constructor(componentDefinition: IComponentDefinitionConfig, container: HTMLElement, options?: loaderOptions);
+        get uiTags(): string[];
         _markedForDisposed: boolean;
         get markedForDisposed(): boolean;
         set markedForDisposed(value: boolean);
@@ -1622,16 +1630,21 @@ declare module "@myop/sdk/helpers/CloudRepository" {
          * Deliberately mutates THIS instance rather than constructing a new repository:
          * CloudRepository.Main is a global singleton shared across bundles (see getGlobalMain),
          * so a second instance would be ignored by every component already using the first.
+         *
+         * @internal
          */
         setDelivery(opts?: {
             minify?: boolean;
             host?: string | null;
             cache?: boolean;
+            flow?: boolean;
         }): void;
+        /** @internal */
         deliveryStats(): {
             host: string;
             minify: boolean;
             cache: boolean;
+            flow: boolean;
             requests: number;
             viaDelivery: number;
             fellBack: number;
@@ -1649,6 +1662,8 @@ declare module "@myop/sdk/helpers/CloudRepository" {
          * Forget what this browser holds, so the next load asks the server.
          * `refresh()` with no ids drops everything; the counterpart to the window for the case
          * where a change has to be visible on THIS load — right after someone publishes.
+         *
+         * @internal
          */
         refreshDelivery(): Promise<void>;
         /**
@@ -1666,6 +1681,12 @@ declare module "@myop/sdk/helpers/CloudRepository" {
          */
         private _localServes;
         private _flushBound;
+        /**
+         * `source: 'h'` = the view was served from a config the page's SERVER embedded
+         * (hydrateV1Component), not from this browser's cache window. Reported as a 4th batch
+         * field (`id:env:n:h`) so our usage data can tell server-rendered views apart; a server
+         * that predates it reads the first three fields and counts the view all the same.
+         */
         private noteLocalServe;
         /** Report on page-hide, which is the only event that reliably fires on mobile. */
         private bindFlush;
@@ -1692,7 +1713,7 @@ declare module "@myop/sdk/helpers/CloudRepository" {
         /**
          * Enable static mode for self-hosted component registries.
          * In static mode, URLs are constructed as file paths instead of query params:
-         *   ${baseUrl}/components/${componentId}/${env}.json
+         * `${baseUrl}/components/${componentId}/${env}.json`
          */
         enableStaticMode(): void;
         /**
@@ -1759,6 +1780,11 @@ declare module "@myop/sdk/helpers/CloudRepository" {
          * skipping the WEBVIEW_READY → fetch → inject round trip entirely.
          */
         getResolvedConfig(componentId: string, env?: string, preview?: boolean): IComponentConfig | null;
+        /**
+         * The `ui:` tags of an already-resolved component (`[]` if it has none or is not
+         * resolved yet). Synchronous, no request: tags arrive with the component itself.
+         */
+        getComponentTags(componentId: string, env?: string, preview?: boolean): string[];
         /**
          * Resolve which (env, preview) pair — and therefore which cache key — a call
          * for `componentId` refers to.
@@ -1783,6 +1809,23 @@ declare module "@myop/sdk/helpers/CloudRepository" {
          * match what a plain `fetchComponentV2(componentId)` would have used.
          */
         hydrateComponent(componentId: string, config: IComponentConfig, env?: string, preview?: boolean): void;
+        /** ids seeded by hydrateV1Component whose first use has not been counted yet */
+        private _hydratedV1;
+        /**
+         * Seed a v1 component's config, so `fetchComponentV1(componentId)` answers from memory
+         * with no request. The v1 counterpart of {@link hydrateComponent}.
+         *
+         * `flow` is what `GET /flow?id=<componentId>&auto=true` returns: either the whole body
+         * (`{item: {...}}`) or its `item`. Typical use is a server that fetched it (with
+         * `&prefetch=1`, so the fetch is not counted as a view) and embedded it in the page.
+         *
+         * The view IS counted: the first time the seeded config is used, it is reported through
+         * /clientUsage (flagged `:h`, recorded as deliveryPath 'hydrated'), so hydrating never makes
+         * usage disappear and server-rendered views stay distinguishable.
+         */
+        hydrateV1Component(componentId: string, flow: IUserFlow | {
+            item: IUserFlow;
+        }): void;
         /**
          * Fetch a v1 component from a flow
          */
@@ -1835,21 +1878,28 @@ declare module "@myop/sdk/helpers/cloudRepositoryHelpers" {
      *     inside the freshness the server promised, is rendered with NO request. Once the
      *     window ends the browser sends back the version it holds instead of re-downloading.
      *   - A preview is never minified and never cached.
-     *   - Only /consume moves. Everything else keeps the host it has today.
+     *   - Only /consume moves. Everything else keeps the host it has today -- unless
+     *     `flow: true`, which also moves v1 component configs (`/flow?auto=true`), with the
+     *     same fallback.
      *   - Asking for `minify` does not force it: the server decides per component, and a
      *     component that is not enabled is served raw, which is not an error.
      *
      * `host` is for us (a staging lane, a local server); leave it out.
+     *
+     * @internal Delivery lane: kept out of the public API reference until it is released.
      */
     export const DELIVERY_HOST = "https://delivery.myop.dev";
+    /** @internal */
     export const delivery: (opts?: {
         minify?: boolean;
         cache?: boolean;
+        flow?: boolean;
         host?: string | null;
     }) => {
         host: string;
         minify: boolean;
         cache: boolean;
+        flow: boolean;
         requests: number;
         viaDelivery: number;
         fellBack: number;
@@ -1865,11 +1915,14 @@ declare module "@myop/sdk/helpers/cloudRepositoryHelpers" {
      * Forget what this browser holds, so the next load asks the server. Use it when a change
      * has to be visible on THIS load — right after someone publishes — rather than within the
      * freshness window.
+     *
+     * @internal
      */
     export const deliveryRefresh: () => Promise<{
         host: string;
         minify: boolean;
         cache: boolean;
+        flow: boolean;
         requests: number;
         viaDelivery: number;
         fellBack: number;
@@ -1884,11 +1937,14 @@ declare module "@myop/sdk/helpers/cloudRepositoryHelpers" {
     /**
      * What answered the last requests, and — the number worth watching — how many times the
      * SDK had to fall back to the default host because the lane did not answer.
+     *
+     * @internal
      */
     export const deliveryStats: () => {
         host: string;
         minify: boolean;
         cache: boolean;
+        flow: boolean;
         requests: number;
         viaDelivery: number;
         fellBack: number;
@@ -1900,11 +1956,12 @@ declare module "@myop/sdk/helpers/cloudRepositoryHelpers" {
         unchanged: number;
         bytesSaved: number;
     };
-    /** Undo delivery(): back to the default host and raw bytes, with no reload. */
+    /** Undo delivery(): back to the default host and raw bytes, with no reload. @internal */
     export const deliveryOff: () => {
         host: string;
         minify: boolean;
         cache: boolean;
+        flow: boolean;
         requests: number;
         viaDelivery: number;
         fellBack: number;
@@ -1919,6 +1976,16 @@ declare module "@myop/sdk/helpers/cloudRepositoryHelpers" {
     export const setCloudRepository: (repository: CloudRepository) => void;
     export const setEnvironment: (env: string) => void;
     export const getResolvedConfig: (componentId: string, env?: string, preview?: boolean) => IComponentConfig;
+    /**
+     * The runtime tags of a loaded/preloaded component: only tags named `ui:...` (e.g.
+     * `ui:beta`). Returns `[]` when it has none or has not been fetched yet.
+     *
+     * ```ts
+     * await preloadComponents([id]);
+     * getComponentTags(id); // ['ui:beta']
+     * ```
+     */
+    export const getComponentTags: (componentId: string, env?: string, preview?: boolean) => string[];
     export const preloadComponents: (ids: string[], env?: string, preview?: boolean) => Promise<PromiseSettledResult<IComponentConfig>[]>;
     /**
      * Seed already-resolved component configs into the SDK cache, with no network
@@ -1938,6 +2005,22 @@ declare module "@myop/sdk/helpers/cloudRepositoryHelpers" {
      * match what a plain `preloadComponents([id])` would have used.
      */
     export const hydrateComponents: (configs: Record<string, IComponentConfig>, env?: string, preview?: boolean) => void;
+    /**
+     * The v1 (iframe component) counterpart of {@link hydrateComponents}: seed configs that a
+     * server already fetched, so `loadComponent` needs no `/flow` request at all.
+     *
+     * ```ts
+     * // server (cache it ~60 s; `prefetch=1` keeps this fetch out of the view count, `for` says which
+     * // page it is for, so the prefetch is attributed to your site — its query string is not stored):
+     * const flow = await (await fetch(`https://cloud.myop.dev/flow?id=${id}&auto=true&prefetch=1&for=${encodeURIComponent(pageUrl)}`)).json();
+     * // embed JSON.stringify(flow) in the page, then on the client:
+     * hydrateV1Components({ [id]: flow });
+     * const cfg = await CloudRepository.Main.fetchComponentV1(id);   // no request
+     * ```
+     *
+     * Each seeded config is counted as a view the first time it is used (via /clientUsage).
+     */
+    export const hydrateV1Components: (flows: Record<string, any>) => void;
 }
 declare module "@myop/sdk/webcomponent/shadowRootRef" {
     import { RootRef } from "@myop/sdk/common";
@@ -2342,7 +2425,7 @@ declare module "@myop/sdk/host/hostSDK" {
         _inspection?: boolean;
         data?: any;
         /**
-         * Raw CSS injected into the component's iframe <head> before first paint.
+         * Raw CSS injected into the component's iframe `<head>` before first paint.
          * Appended last so it overrides the component's own styles via cascade order.
          * Useful for theming v2 (HTML) components — colors, fonts, spacing, etc.
          */

package/dist/cjs/{_IframeSDK.3a412cd4.js → _IframeSDK.49662e01.js}

@@ -1017,6 +1017,10 @@ var BaseMyopComponent = class {
       }
     });
   }
+  get uiTags() {
+    var _a;
+    return ((_a = this.componentDefinition) == null ? void 0 : _a.uiTags) || [];
+  }
   get markedForDisposed() {
     return this._markedForDisposed;
   }
@@ -2096,6 +2100,21 @@ var addQueryParam = (url, param, value) => {
   urlObj.searchParams.append(param, value);
   return urlObj.toString();
 };
+var showsSamePage = (frame, url) => {
+  const current = frame.getAttribute("src");
+  if (!current || !url) return false;
+  const norm = (u) => {
+    const x = new URL(u, document.baseURI);
+    x.hash = "";
+    if (x.pathname.length > 1) x.pathname = x.pathname.replace(/\/$/, "");
+    return x.href;
+  };
+  try {
+    return norm(current) === norm(url);
+  } catch (e) {
+    return false;
+  }
+};
 var MyopIframeLoader = class extends BaseMyopLoader {
   constructor() {
     super(...arguments);
@@ -2105,9 +2124,10 @@ var MyopIframeLoader = class extends BaseMyopLoader {
       let IframeElement;
       const typedLoaderConfig = skin.loader;
       if ((container == null ? void 0 : container.nodeName) === "IFRAME") {
-        console.log("needs to load into an exsisting Iframe...", typedLoaderConfig.url, container);
         IframeElement = container;
-        IframeElement.src = typedLoaderConfig.url;
+        if (!showsSamePage(IframeElement, typedLoaderConfig.url)) {
+          IframeElement.src = typedLoaderConfig.url;
+        }
       } else {
         const uniqId = uuidv4();
         const domId = "myop-comp-".concat(uniqId);
@@ -2250,7 +2270,7 @@ var WebcomponentLoader = class extends BaseMyopLoader {
 };
 
 // version:myop-sdk-version
-var myop_sdk_version_default = "0.4.0-beta.4";
+var myop_sdk_version_default = "0.4.0-beta.6";
 
 // src/helpers/deliveryStore.ts
 var DB_NAME = "myop-delivery";
@@ -2407,7 +2427,10 @@ var convertV2VariantToComponentConfig = (config) => {
           loader: config.consume_variant[0].loader
         }
       ],
-      defaultSkin: 0
+      defaultSkin: 0,
+      // Only `ui:` tags ever reach the client; the server filters, absent = none.
+      // @ts-ignore
+      uiTags: Array.isArray(config.uiTags) ? config.uiTags : []
     },
     name: config.name
   };
@@ -2449,7 +2472,7 @@ var _CloudRepository = class _CloudRepository {
      * Opt-in delivery settings, set by myop.delivery(). Off means: this file behaves
      * EXACTLY as it did before — same host, same URL, same everything.
      */
-    __publicField(this, "_delivery", { minify: false, host: null, cache: false });
+    __publicField(this, "_delivery", { minify: false, host: null, cache: false, flow: false });
     /**
      * What actually happened, for myop.delivery.stats(). `fellBack` is the number that
      * matters: it is how you find out the lane is unhealthy without waiting for a
@@ -2484,6 +2507,9 @@ var _CloudRepository = class _CloudRepository {
      */
     __publicField(this, "_localServes", /* @__PURE__ */ new Map());
     __publicField(this, "_flushBound", false);
+    // ============ V1 Methods (Legacy) ============
+    /** ids seeded by hydrateV1Component whose first use has not been counted yet */
+    __publicField(this, "_hydratedV1", /* @__PURE__ */ new Set());
   }
   static get Main() {
     const globalMain = getGlobalMain();
@@ -2519,32 +2545,46 @@ var _CloudRepository = class _CloudRepository {
    * Deliberately mutates THIS instance rather than constructing a new repository:
    * CloudRepository.Main is a global singleton shared across bundles (see getGlobalMain),
    * so a second instance would be ignored by every component already using the first.
+   *
+   * @internal
    */
   setDelivery(opts = {}) {
     if (opts.minify !== void 0) this._delivery.minify = !!opts.minify;
     if (opts.host !== void 0) this._delivery.host = opts.host;
     if (opts.cache !== void 0) this._delivery.cache = !!opts.cache;
+    if (opts.flow !== void 0) this._delivery.flow = !!opts.flow;
   }
+  /** @internal */
   deliveryStats() {
     var _a;
     return __spreadProps(__spreadValues({}, this._deliveryStats), {
       host: (_a = this._delivery.host) != null ? _a : _CloudRepository.DEFAULT_HOST,
       minify: this._delivery.minify,
-      cache: this._delivery.cache
+      cache: this._delivery.cache,
+      flow: this._delivery.flow
     });
   }
   /**
    * Forget what this browser holds, so the next load asks the server.
    * `refresh()` with no ids drops everything; the counterpart to the window for the case
    * where a change has to be visible on THIS load — right after someone publishes.
+   *
+   * @internal
    */
   async refreshDelivery() {
     await deliveryStore.clear();
   }
-  noteLocalServe(componentId, env) {
-    const cur = this._localServes.get(componentId);
+  /**
+   * `source: 'h'` = the view was served from a config the page's SERVER embedded
+   * (hydrateV1Component), not from this browser's cache window. Reported as a 4th batch
+   * field (`id:env:n:h`) so our usage data can tell server-rendered views apart; a server
+   * that predates it reads the first three fields and counts the view all the same.
+   */
+  noteLocalServe(componentId, env, source) {
+    const key = source ? "".concat(componentId, ":").concat(source) : componentId;
+    const cur = this._localServes.get(key);
     if (cur) cur.count++;
-    else this._localServes.set(componentId, { env, count: 1 });
+    else this._localServes.set(key, { id: componentId, env, count: 1, source });
     this.bindFlush();
   }
   /** Report on page-hide, which is the only event that reliably fires on mobile. */
@@ -2564,7 +2604,7 @@ var _CloudRepository = class _CloudRepository {
    */
   flushLocalServes() {
     if (!this._localServes.size) return;
-    const batch = [...this._localServes.entries()].map(([id, v]) => "".concat(id, ":").concat(v.env, ":").concat(v.count)).join(",");
+    const batch = [...this._localServes.entries()].map(([, v]) => "".concat(v.id, ":").concat(v.env, ":").concat(v.count).concat(v.source ? ":" + v.source : "")).join(",");
     this._localServes.clear();
     try {
       const url = "".concat(this.deliveryHost(), "/clientUsage?b=").concat(encodeURIComponent(batch));
@@ -2613,7 +2653,7 @@ var _CloudRepository = class _CloudRepository {
   /**
    * Enable static mode for self-hosted component registries.
    * In static mode, URLs are constructed as file paths instead of query params:
-   *   ${baseUrl}/components/${componentId}/${env}.json
+   * `${baseUrl}/components/${componentId}/${env}.json`
    */
   enableStaticMode() {
     this._staticMode = true;
@@ -2822,6 +2862,14 @@ var _CloudRepository = class _CloudRepository {
     const { cacheKey } = this.resolveParams(componentId, env, preview);
     return ((_a = this.variants[cacheKey]) == null ? void 0 : _a.resolved) || null;
   }
+  /**
+   * The `ui:` tags of an already-resolved component (`[]` if it has none or is not
+   * resolved yet). Synchronous, no request: tags arrive with the component itself.
+   */
+  getComponentTags(componentId, env, preview) {
+    var _a, _b;
+    return ((_b = (_a = this.getResolvedConfig(componentId, env, preview)) == null ? void 0 : _a.type) == null ? void 0 : _b.uiTags) || [];
+  }
   /**
    * Resolve which (env, preview) pair — and therefore which cache key — a call
    * for `componentId` refers to.
@@ -2866,7 +2914,27 @@ var _CloudRepository = class _CloudRepository {
     this.variants[cacheKey] = promise;
     this.preloadedComponents[componentId] = { env: resolvedEnv, preview: usePreview };
   }
-  // ============ V1 Methods (Legacy) ============
+  /**
+   * Seed a v1 component's config, so `fetchComponentV1(componentId)` answers from memory
+   * with no request. The v1 counterpart of {@link hydrateComponent}.
+   *
+   * `flow` is what `GET /flow?id=<componentId>&auto=true` returns: either the whole body
+   * (`{item: {...}}`) or its `item`. Typical use is a server that fetched it (with
+   * `&prefetch=1`, so the fetch is not counted as a view) and embedded it in the page.
+   *
+   * The view IS counted: the first time the seeded config is used, it is reported through
+   * /clientUsage (flagged `:h`, recorded as deliveryPath 'hydrated'), so hydrating never makes
+   * usage disappear and server-rendered views stay distinguishable.
+   */
+  hydrateV1Component(componentId, flow) {
+    var _a, _b;
+    const item = (_a = flow == null ? void 0 : flow.item) != null ? _a : flow;
+    if (!((_b = item == null ? void 0 : item.components) == null ? void 0 : _b.length)) {
+      throw new Error("hydrateV1Component(".concat(componentId, "): not a /flow?auto=true response"));
+    }
+    this.userFlows[componentId] = Promise.resolve(item);
+    this._hydratedV1.add(componentId);
+  }
   /**
    * Fetch a v1 component from a flow
    */
@@ -2880,13 +2948,15 @@ var _CloudRepository = class _CloudRepository {
     }
   }
   async fetchAutoFlow(componentId) {
+    if (this._hydratedV1.delete(componentId)) {
+      this.noteLocalServe(componentId, "v1_auto_flow", "h");
+    }
     if (!this.userFlows[componentId]) {
       this.userFlows[componentId] = new Promise(
         async (resolve, reject) => {
           try {
-            const res = await fetch(
-              "".concat(this._baseUrl, "/flow?id=").concat(componentId, "&auto=true")
-            );
+            const path = "/flow?id=".concat(componentId, "&auto=true");
+            const res = this._delivery.flow && this._delivery.host ? await this.deliveryFetch(path) : await fetch("".concat(this._baseUrl).concat(path));
             const json = await res.json();
             resolve(json.item);
           } catch (e) {
@@ -2935,11 +3005,12 @@ var CloudRepository = _CloudRepository;
 var _cloudRepository = CloudRepository.Main;
 var DELIVERY_HOST = "https://delivery.myop.dev";
 var delivery = (opts = {}) => {
-  var _a, _b;
-  const wantsLane = opts.minify !== false || opts.cache === true;
+  var _a, _b, _c;
+  const wantsLane = opts.minify !== false || opts.cache === true || opts.flow === true;
   _cloudRepository.setDelivery({
     minify: (_a = opts.minify) != null ? _a : false,
     cache: (_b = opts.cache) != null ? _b : false,
+    flow: (_c = opts.flow) != null ? _c : false,
     host: opts.host !== void 0 ? opts.host : wantsLane ? DELIVERY_HOST : null
   });
   return deliveryStats();
@@ -2950,9 +3021,14 @@ var deliveryRefresh = async () => {
 };
 var deliveryStats = () => _cloudRepository.deliveryStats();
 var deliveryOff = () => {
-  _cloudRepository.setDelivery({ minify: false, cache: false, host: null });
+  _cloudRepository.setDelivery({ minify: false, cache: false, flow: false, host: null });
   return deliveryStats();
 };
+var hydrateV1Components = (flows) => {
+  for (const [id, flow] of Object.entries(flows)) {
+    _cloudRepository.hydrateV1Component(id, flow);
+  }
+};
 
 // src/webcomponent/messageHandlers/BaseWebComponentMessageHandler.ts
 var BaseWebComponentMessageHandler = class extends BaseContextMessageHandler {
@@ -4019,6 +4095,9 @@ if (window.myop && !window.myop.delivery) {
   api.refresh = deliveryRefresh;
   window.myop.delivery = api;
 }
+if (window.myop && !window.myop.hydrateV1) {
+  window.myop.hydrateV1 = hydrateV1Components;
+}
 var hostSDK = window.myop.hostSDK;
 defineDynamicImport("hostSDK", hostSDK);