@kubex/zinc 1.1.72 → 1.1.74

package/src/components/page/page.component.ts

@@ -62,6 +62,7 @@ export default class ZnPage extends ZnTabs {
   @state() private hasExpandingActions = false;
   private actionObserver: MutationObserver | null = null;
   private tabObserver: MutationObserver | null = null;
+  private pageHistoryKey: string | null = null;
 
   async connectedCallback() {
     const connected = super.connectedCallback();
@@ -281,22 +282,45 @@ export default class ZnPage extends ZnTabs {
 
   private handleNavigationSelect(event: ZnSelectEvent) {
     const item = event.detail.item as HTMLElement;
+    if (this.getNavigationItemPage(item) !== this) {
+      return;
+    }
+
     const tabUri = item.getAttribute('tab-uri');
     const tabId = item.getAttribute('tab');
 
     if (tabUri) {
-      this.clickTab(item, false);
+      this.clickTab(item, false, true);
       this.syncNavigationActive(item);
       return;
     }
 
     if (tabId !== null) {
-      this.activateTab(tabId, true);
+      this.activateTab(tabId, true, true);
     }
   }
 
-  private activateTab(tabId: string, store: boolean) {
-    this.setActiveTab(tabId, store, false);
+  private getNavigationItemPage(item: HTMLElement): ZnPage | null {
+    let current: Node | null = item;
+
+    while (current) {
+      if (current instanceof ZnPage) {
+        return current;
+      }
+
+      const root = current.getRootNode();
+      if (!(root instanceof ShadowRoot)) {
+        return item.closest<ZnPage>('zn-page');
+      }
+
+      current = root.host;
+    }
+
+    return null;
+  }
+
+  private activateTab(tabId: string, store: boolean, pushHistory = false) {
+    this.setActiveTab(tabId, store, false, null, pushHistory);
     const navItem = this.shadowRoot?.querySelector<HTMLElement>(`zn-navbar li[tab="${CSS.escape(tabId)}"]`);
     if (navItem) {
       this.syncNavigationActive(navItem);
@@ -304,6 +328,15 @@ export default class ZnPage extends ZnTabs {
   }
 
   private activateInitialPageTab() {
+    const restoredTab = this.getStoredTab();
+    if (restoredTab !== null) {
+      const definition = this.tabDefinitions.find(tab => tab.id === restoredTab || tab.uri === restoredTab);
+      if (definition) {
+        this.activateTabDefinition(definition);
+        return;
+      }
+    }
+
     const preselected = this.tabDefinitions.find(tab => tab.selected);
     if (preselected) {
       this.activateTabDefinition(preselected);
@@ -318,7 +351,39 @@ export default class ZnPage extends ZnTabs {
     }
   }
 
-  private activateTabDefinition(tab: TabDefinition) {
+  // Pages have no store-key, so they persist against their own identity.
+  protected getTabStoreKey(): string {
+    return this.getPageHistoryKey();
+  }
+
+  // A page's default is its preselected tab, or the first one - not the empty
+  // active tab zn-tabs starts from.
+  protected activateDefaultTab() {
+    const preselected = this.tabDefinitions.find(tab => tab.selected) ?? this.tabDefinitions[0];
+    if (preselected) {
+      this.activateTabDefinition(preselected, true);
+    }
+  }
+
+  private getPageHistoryKey(): string {
+    if (this.pageHistoryKey !== null) {
+      return this.pageHistoryKey;
+    }
+
+    const pages: ZnPage[] = [this];
+    let ancestor = this.parentElement?.closest<ZnPage>('zn-page') ?? null;
+    while (ancestor) {
+      pages.unshift(ancestor);
+      ancestor = ancestor.parentElement?.closest<ZnPage>('zn-page') ?? null;
+    }
+
+    this.pageHistoryKey = pages
+      .map(page => page.id || page.getAttribute('caption') || 'page')
+      .join('/');
+    return this.pageHistoryKey;
+  }
+
+  private activateTabDefinition(tab: TabDefinition, store = false) {
     if (tab.uri) {
       const navItem = this.findNavItemForUri(tab.uri);
       if (navItem) {
@@ -327,7 +392,7 @@ export default class ZnPage extends ZnTabs {
         return;
       }
     }
-    this.activateTab(tab.id, false);
+    this.activateTab(tab.id, store);
   }
 
   private findNavItemForUri(uri: string): HTMLElement | null {

package/src/components/page/page.test.ts

@@ -85,6 +85,214 @@ describe('<zn-page>', () => {
     expect(getComputedStyle(selectedTab).display).to.not.equal('none');
   });
 
+  describe('tab persistence', () => {
+    const originalHref = window.location.href;
+    let locationCount = 0;
+
+    const renderPage = () => fixture<ZnPage>(html`
+      <zn-page caption="Persisted Page">
+        <zn-tab caption="Overview">Overview Content</zn-tab>
+        <zn-tab caption="Billing">Billing Content</zn-tab>
+        <zn-tab caption="Notes">Notes Content</zn-tab>
+      </zn-page>
+    `);
+
+    const clickTab = async (page: ZnPage, index: number) => {
+      const navbar = page.shadowRoot!.querySelector('zn-navbar')!;
+      navbar.shadowRoot!.querySelectorAll<HTMLElement>('li:not(.more)')[index].click();
+      await aTimeout(40);
+    };
+
+    const clickBilling = (page: ZnPage) => clickTab(page, 1);
+
+    const goBack = async () => {
+      await new Promise<void>(resolve => {
+        window.addEventListener('popstate', () => resolve(), {once: true});
+        window.history.back();
+      });
+      await aTimeout(40);
+    };
+
+    beforeEach(() => {
+      locationCount += 1;
+      window.history.pushState({}, '', `?page-test=case-${locationCount}`);
+    });
+
+    afterEach(() => window.history.replaceState({}, '', originalHref));
+
+    it('restores the active tab when the page is reloaded or returned to', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+      await clickBilling(page);
+      expect(page.getAttribute('active')).to.equal('billing');
+      page.remove();
+
+      // A reload replaces the document; the shell may also replace the history
+      // entry's state, so restoring must not depend on that state surviving.
+      window.history.replaceState({uri: window.location.pathname}, '');
+      window.dispatchEvent(new PopStateEvent('popstate'));
+
+      const restoredPage = await renderPage();
+      await aTimeout(40);
+      expect(restoredPage.getAttribute('active')).to.equal('billing');
+    });
+
+    it('uses the default tab when navigating to the page', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+      await clickBilling(page);
+      page.remove();
+
+      const stored = window.location.search;
+      window.history.pushState({}, '', '?page-test=elsewhere');
+      window.history.pushState({}, '', stored);
+
+      const freshPage = await renderPage();
+      await aTimeout(40);
+      expect(freshPage.getAttribute('active')).to.equal('');
+    });
+
+    it('restores a tab cycled without the navigation', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+
+      // Keyboard shortcuts cycle tabs directly, bypassing the navbar.
+      page.nextTab();
+      await aTimeout(40);
+      expect(page.getAttribute('active')).to.equal('billing');
+      page.remove();
+
+      window.dispatchEvent(new PopStateEvent('popstate'));
+      const restoredPage = await renderPage();
+      await aTimeout(40);
+      expect(restoredPage.getAttribute('active')).to.equal('billing');
+    });
+
+    it('steps back through each tab that was opened', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+
+      await clickTab(page, 1);
+      expect(page.getAttribute('active')).to.equal('billing');
+      await clickTab(page, 2);
+      expect(page.getAttribute('active')).to.equal('notes');
+
+      await goBack();
+      expect(page.getAttribute('active')).to.equal('billing');
+
+      await goBack();
+      expect(page.getAttribute('active')).to.equal('');
+    });
+
+    it('keeps the open tab when stepping back onto an entry that records no tab', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+
+      // The shell pushes an entry of its own for every document load, recording
+      // no tab of the page already on screen.
+      window.history.pushState({uri: window.location.pathname}, '', window.location.href);
+
+      await clickTab(page, 2);
+      expect(page.getAttribute('active')).to.equal('notes');
+
+      // Stepping onto the shell's entry says nothing about the tab, so the open
+      // one stays rather than the page dropping back to its first tab.
+      await goBack();
+      expect(page.getAttribute('active')).to.equal('notes');
+    });
+
+    it('keeps the tab history when the page is reloaded', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+      await clickTab(page, 1);
+      await clickTab(page, 2);
+      expect(page.getAttribute('active')).to.equal('notes');
+      page.remove();
+
+      // A reload replaces the document, and the shell pushes a fresh entry for it.
+      window.history.pushState({uri: window.location.pathname}, '', window.location.href);
+      window.dispatchEvent(new PopStateEvent('popstate'));
+
+      const reloadedPage = await renderPage();
+      await aTimeout(40);
+      expect(reloadedPage.getAttribute('active')).to.equal('notes');
+
+      await goBack();
+      expect(reloadedPage.getAttribute('active')).to.equal('notes');
+
+      await goBack();
+      expect(reloadedPage.getAttribute('active')).to.equal('billing');
+    });
+
+    it('steps straight back to the previous tab when the reloaded entry is kept', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+      await clickTab(page, 1);
+      await clickTab(page, 2);
+      expect(page.getAttribute('active')).to.equal('notes');
+      page.remove();
+
+      // The shell records the uri on the entry the document loaded on, rather
+      // than pushing a second entry for the same page.
+      const state = window.history.state as Record<string, unknown> | null;
+      window.history.replaceState({...state, uri: window.location.pathname}, '', window.location.href);
+      window.dispatchEvent(new PopStateEvent('popstate'));
+
+      const reloadedPage = await renderPage();
+      await aTimeout(40);
+      expect(reloadedPage.getAttribute('active')).to.equal('notes');
+
+      await goBack();
+      expect(reloadedPage.getAttribute('active')).to.equal('billing');
+
+      await goBack();
+      expect(reloadedPage.getAttribute('active')).to.equal('');
+    });
+
+    it('keeps the tab when the page is re-rendered at the same location', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+      await clickBilling(page);
+      page.remove();
+
+      const rerenderedPage = await renderPage();
+      await aTimeout(40);
+      expect(rerenderedPage.getAttribute('active')).to.equal('billing');
+    });
+
+    it('forgets the tab and its history once the page is navigated away from', async () => {
+      const page = await renderPage();
+      await aTimeout(40);
+      await clickBilling(page);
+      const pageLocation = window.location.search;
+      page.remove();
+
+      window.history.pushState({}, '', '?page-test=departed');
+      await aTimeout(40);
+
+      await goBack();
+      expect(window.location.search).to.equal(pageLocation);
+
+      const returnedPage = await renderPage();
+      await aTimeout(40);
+      expect(returnedPage.getAttribute('active')).to.equal('');
+    });
+
+    it('adds one history entry per tab, and none for the tab it opens on', async () => {
+      const lengthBeforeRender = window.history.length;
+      const page = await renderPage();
+      await aTimeout(40);
+      expect(window.history.length).to.equal(lengthBeforeRender);
+
+      await clickTab(page, 1);
+      expect(window.history.length).to.equal(lengthBeforeRender + 1);
+
+      // Reselecting the open tab is not a new step.
+      await clickTab(page, 1);
+      expect(window.history.length).to.equal(lengthBeforeRender + 1);
+    });
+  });
+
   it('creates uri tab panels from page navigation items', async () => {
     const el = await fixture<ZnPage>(html`
       <zn-page caption="Page Title">
@@ -142,6 +350,45 @@ describe('<zn-page>', () => {
     expect(innerDynamicPanel.hasAttribute('selected')).to.equal(true);
   });
 
+  it('keeps nested page tab selections scoped to the nested page', async () => {
+    const outerPage = await fixture<ZnPage>(html`
+      <zn-page caption="Outer Page">
+        <zn-tab caption="Outer One">
+          <zn-page caption="Inner Page" nested>
+            <zn-tab caption="Inner One">Inner One Content</zn-tab>
+            <zn-tab caption="Inner Two">Inner Two Content</zn-tab>
+          </zn-page>
+        </zn-tab>
+        <zn-tab caption="Outer Two">Outer Two Content</zn-tab>
+      </zn-page>
+    `);
+    await aTimeout(80);
+
+    const innerPage = outerPage.querySelector<ZnPage>('zn-page')!;
+    const outerNavbar = outerPage.shadowRoot!.querySelector('zn-navbar')!;
+    const innerNavbar = innerPage.shadowRoot!.querySelector('zn-navbar')!;
+    const innerSecondItem = innerNavbar.shadowRoot!.querySelectorAll<HTMLElement>('li:not(.more)')[1];
+
+    innerSecondItem.click();
+    await aTimeout(40);
+
+    expect(innerPage.getAttribute('active')).to.equal('inner-two');
+    expect(outerPage.getAttribute('active')).to.equal('outer-one');
+    expect(outerPage.shadowRoot!.querySelector('#outer-one')!.hasAttribute('selected')).to.equal(true);
+    expect(outerPage.shadowRoot!.querySelector('#outer-two')!.hasAttribute('selected')).to.equal(false);
+
+    // Even if a composed selection is delivered to an ancestor navbar, the
+    // ancestor page must ignore an item owned by the nested page.
+    outerNavbar.dispatchEvent(new CustomEvent('zn-select', {
+      bubbles: true,
+      composed: true,
+      detail: {item: innerSecondItem}
+    }));
+    await aTimeout(20);
+
+    expect(outerPage.getAttribute('active')).to.equal('outer-one');
+  });
+
   it('uses an explicit zn-tab for overview content', async () => {
     const el = await fixture<ZnPage>(html`
       <zn-page caption="Page Title">

package/src/components/preview-frame/preview-frame.component.ts

@@ -1,4 +1,4 @@
-import {type CSSResultGroup, html, unsafeCSS} from 'lit';
+import {type CSSResultGroup, html, type PropertyValues, unsafeCSS} from 'lit';
 import {MutationController} from '@lit-labs/observers/mutation-controller.js';
 import {property, query, state} from 'lit/decorators.js';
 import {styleMap} from 'lit/directives/style-map.js';
@@ -19,8 +19,10 @@ export type PreviewFrameDevice = keyof typeof DEVICE_WIDTHS;
  * protocol: answers the frame's ready handshake with a config payload fetched
  * from data-uri, auto-saves watched forms on change, refreshes the preview
  * after each save (its own, or a shell-driven save of a `refresh-on` form),
- * and accepts a theme payload via setTheme() that is retained and replayed
- * after every ready handshake.
+ * accepts a theme payload via setTheme() that is retained and replayed
+ * after every ready handshake, and grows the frame to a content height the
+ * embed reports so the panel scrolls an overflowing page.
+ *
  * @documentation https://zinc.style/components/preview-frame
  * @status experimental
  * @since 1.0
@@ -102,12 +104,34 @@ export default class ZnPreviewFrame extends ZincElement {
   /** Backdrop behind the stage: `dots` (default) is the canvas dot grid; `panel` is a plain `rgb(var(--zn-panel))` fill. */
   @property({reflect: true}) backdrop: 'dots' | 'panel' = 'dots';
 
+  /**
+   * Lets pointer input through to the embedded page. The preview is inert by
+   * default: clicks never reach the frame, so the previewed page can't be
+   * navigated or submitted from inside the preview. Cross-origin content can't
+   * be reached from here to cancel its own handlers, so this blocks pointer
+   * input entirely — hover goes with it. Scrolling doesn't: an overflowing
+   * page is scrolled by the panel rather than by the frame (see _contentHeight).
+   */
+  @property({type: Boolean, reflect: true}) interactive = false;
+
   @query('iframe') frame: HTMLIFrameElement;
 
   @state() private error = '';
 
+  /**
+   * Height of the embedded page's content, when it's known: reported by the
+   * embed (`height` on hp-preview:rendered, or an hp-preview:height message) or
+   * measured directly for a same-origin embed. The frame is laid out at this
+   * height rather than the panel's, so the page never scrolls inside the frame
+   * — the panel scrolls instead, which is what makes an overflowing preview
+   * reachable while pointer input to the frame is blocked. 0 = unknown, and the
+   * frame falls back to filling the panel.
+   */
+  @state() private _contentHeight = 0;
+
   private _generation = 0;
   private _theme: Record<string, unknown> | undefined;
+  private _contentObserver: ResizeObserver | undefined;
 
   private readonly _watchedForms = new Set<HTMLFormElement>();
   private readonly _refreshForms = new Set<HTMLFormElement>();
@@ -136,9 +160,15 @@ export default class ZnPreviewFrame extends ZincElement {
     }
   }
 
+  protected willUpdate(changed: PropertyValues<this>) {
+    if (changed.has('src')) this._resetContentHeight();
+  }
+
   disconnectedCallback() {
     super.disconnectedCallback();
     window.removeEventListener('message', this._onMessage);
+    this._contentObserver?.disconnect();
+    this._contentObserver = undefined;
     this._watchedForms.forEach(form => this._detachForm(form));
     this._watchedForms.clear();
     this._refreshForms.forEach(form => form.removeEventListener('complete', this._onShellSave));
@@ -150,7 +180,7 @@ export default class ZnPreviewFrame extends ZincElement {
     if (e.origin !== this.frameOrigin) return;
     if (!this.frame || e.source !== this.frame.contentWindow) return;
 
-    const data = e.data as {type?: string; message?: string} | undefined;
+    const data = e.data as { type?: string; message?: string; height?: unknown } | undefined;
     switch (data?.type) {
       case 'hp-preview:ready':
         // config first: the embed applies the theme on top of a rendered page
@@ -158,6 +188,10 @@ export default class ZnPreviewFrame extends ZincElement {
         break;
       case 'hp-preview:rendered':
         this.error = '';
+        this._applyContentHeight(data.height);
+        break;
+      case 'hp-preview:height':
+        this._applyContentHeight(data.height);
         break;
       case 'hp-preview:error':
         this._fail(String(data.message ?? 'Preview failed to render'));
@@ -165,6 +199,41 @@ export default class ZnPreviewFrame extends ZincElement {
     }
   };
 
+  private _applyContentHeight(height: unknown) {
+    const value = Math.round(Number(height));
+    if (!Number.isFinite(value) || value <= 0) return;
+    this._contentHeight = value;
+  }
+
+  private _resetContentHeight() {
+    this._contentHeight = 0;
+    this._contentObserver?.disconnect();
+    this._contentObserver = undefined;
+  }
+
+  // Same-origin embeds don't need to implement the height half of the protocol —
+  // their document can be measured from here.
+  private readonly _onFrameLoad = () => {
+    this._contentObserver?.disconnect();
+    this._contentObserver = undefined;
+
+    let root: HTMLElement | null | undefined;
+    try {
+      root = this.frame?.contentDocument?.documentElement;
+    } catch {
+      return; // cross-origin: the embed has to report its own height
+    }
+    if (!root) return;
+
+    const measure = () => {
+      const measured = root.getBoundingClientRect().height;
+      if (measured > (this.frame?.clientHeight ?? 0)) this._applyContentHeight(measured);
+    };
+    measure();
+    this._contentObserver = new ResizeObserver(measure);
+    this._contentObserver.observe(root);
+  };
+
   /** Re-fetches the payload and pushes a fresh config to the preview. */
   refresh() {
     return this._sendConfig();
@@ -327,26 +396,33 @@ export default class ZnPreviewFrame extends ZincElement {
     // transformed back down, so the frame fills the panel while the content
     // renders smaller and more of the page is visible. Percentage width means
     // nothing is measured — no layout feedback loop.
+    const content = this.error ? 0 : this._contentHeight;
     const iframeStyles = this.fill
-      ? {width: '100%', height: '100%'}
+      ? {width: '100%', height: content ? `max(${content}px, 100%)` : '100%'}
       : {
         width: `${100 / zoom}%`,
-        height: `${this.minHeight / zoom}px`,
+        height: `${Math.max(content, this.minHeight / zoom)}px`,
         transform: `scale(${zoom})`,
         transformOrigin: '0 0',
       };
     const containerStyles = this.fill
       ? {height: '100%', minHeight: `${this.minHeight}px`}
       : {height: `${this.minHeight}px`};
+    const stageStyles: Record<string, string> = {
+      width: DEVICE_WIDTHS[this.device] ?? DEVICE_WIDTHS.desktop,
+    };
+    if (content) {
+      stageStyles.height = this.fill ? `max(${content}px, 100%)` : `${Math.max(content * zoom, this.minHeight)}px`;
+    }
 
     return html`
       <div part="base" class="preview" style="${styleMap(containerStyles)}">
-        <div part="stage" class="preview__stage"
-             style="${styleMap({width: DEVICE_WIDTHS[this.device] ?? DEVICE_WIDTHS.desktop})}">
+        <div part="stage" class="preview__stage" style="${styleMap(stageStyles)}">
           <iframe part="iframe"
                   src="${this.src}"
                   title="Payment form preview"
                   allow="local-network-access"
+                  @load="${this._onFrameLoad}"
                   style="${styleMap(iframeStyles)}"></iframe>
         </div>
         ${this.error ? html`

package/src/components/preview-frame/preview-frame.scss

@@ -11,7 +11,8 @@
 .preview {
   position: relative;
   width: 100%;
-  overflow: hidden;
+  overflow-x: hidden;
+  overflow-y: auto;
 
   // Matches page-builder's canvas.
   background:
@@ -36,11 +37,16 @@ iframe {
   display: block;
   width: 100%;
   border: 0;
+  pointer-events: none;
   // Iframes are transparent by default, so without this the dot grid would show
   // through any embed that doesn't set its own background.
   background: rgb(var(--zn-body));
 }
 
+:host([interactive]) iframe {
+  pointer-events: auto;
+}
+
 .preview__error {
   position: absolute;
   inset: 0;