@kubex/zinc 1.1.158 → 1.1.160

package/docs/pages/components/page.md

@@ -133,6 +133,21 @@ Use `priority` to control tab order. Lower numbers appear first after the empty-
 </zn-page>
 ```
 
+### Linking to a Tab
+
+Give any element in the page content a `tab` attribute holding a tab's `id` to open that tab when it is clicked. Links inside a nested `zn-page` or `zn-tabs` open tabs in that nested container.
+
+```html:preview
+<zn-page caption="Scorecard">
+  <zn-tab caption="Details" id="details">
+    <zn-button tab="section-general" icon="edit">Edit General section</zn-button>
+  </zn-tab>
+  <zn-tab caption="General" id="section-general">
+    General section settings
+  </zn-tab>
+</zn-page>
+```
+
 ### Dynamic Tabs
 
 Set `uri` on `zn-tab` to create a dynamic tab. The generated navigation item receives `tab-uri`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.158",
+  "version": "1.1.160",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

package/src/components/filter-container/filter-container.component.ts

@@ -26,62 +26,41 @@ export default class ZnFilterContainer extends ZincElement {
 
   @property() attr = 'filter';
 
+  private _filterFrame = 0;
+
   public handleSearchChange(event: Event) {
-    // get all element that have data-'this.attr' attribute
-    const filterableElements = this.querySelectorAll(`[data-${this.attr}]`);
-    const input = event.target as HTMLInputElement;
-    const searchTerm = input.value.toLowerCase();
+    const searchTerm = (event.target as HTMLInputElement).value.toLowerCase();
+    cancelAnimationFrame(this._filterFrame);
+    this._filterFrame = requestAnimationFrame(() => this.applyFilter(searchTerm));
+  }
 
-    filterableElements.forEach((el) => {
-      const filterValue = el.getAttribute(`data-${this.attr}`)?.toLowerCase() || '';
-      if (filterValue.includes(searchTerm)) {
-        (el as HTMLElement).style.display = '';
-      } else {
-        (el as HTMLElement).style.display = 'none';
-      }
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    cancelAnimationFrame(this._filterFrame);
+  }
 
-      const panel = el.closest('zn-panel');
-      if (panel) {
-        const panelItems = panel.querySelectorAll(`[data-${this.attr}]`);
-        let anyVisible = false;
-        panelItems.forEach((item) => {
-          if ((item as HTMLElement).style.display !== 'none') {
-            anyVisible = true;
-          }
+  private applyFilter(searchTerm: string) {
+    const attr = `data-${this.attr}`;
+    const filterableElements = this.querySelectorAll<HTMLElement>(`[${attr}]`);
+    const panels = new Map<HTMLElement, boolean>();
+    const accordions = new Map<HTMLElement, boolean>();
+    let anyVisibleElements = false;
 
-        });
-        if (anyVisible) {
-          (panel as HTMLElement).style.display = '';
-        } else {
-          (panel as HTMLElement).style.display = 'none';
-        }
-      }
+    filterableElements.forEach((el) => {
+      const visible = searchTerm === '' || (el.getAttribute(attr)?.toLowerCase() || '').includes(searchTerm);
+      setDisplay(el, visible);
+      if (visible) anyVisibleElements = true;
 
-      const accordionItem = el.closest('zn-accordion');
-      if (accordionItem) {
-        const itemElements = accordionItem.querySelectorAll(`[data-${this.attr}]`);
-        let anyVisible = false;
-        itemElements.forEach((item) => {
-          if ((item as HTMLElement).style.display !== 'none') {
-            anyVisible = true;
-          }
-        });
+      const panel = el.closest<HTMLElement>('zn-panel');
+      if (panel) panels.set(panel, (panels.get(panel) ?? false) || visible);
 
-        if (anyVisible) {
-          (accordionItem as HTMLElement).style.display = '';
-        }
-      }
+      const accordion = el.closest<HTMLElement>('zn-accordion');
+      if (accordion) accordions.set(accordion, (accordions.get(accordion) ?? false) || visible);
     });
 
-    if (searchTerm === '') {
-      filterableElements.forEach((el) => {
-        (el as HTMLElement).style.display = '';
-      });
-    }
-
-    // if nothing is visible, show a "no results found" message
-    const anyVisibleElements = Array.from(filterableElements).some((el) => {
-      return (el as HTMLElement).style.display !== 'none';
+    panels.forEach((visible, panel) => setDisplay(panel, visible));
+    accordions.forEach((visible, accordion) => {
+      if (visible) setDisplay(accordion, true);
     });
 
     let noResultsMessage = this.querySelector<HTMLElement>('.no-results-message');
@@ -107,3 +86,8 @@ export default class ZnFilterContainer extends ZincElement {
       <slot></slot> `;
   }
 }
+
+function setDisplay(el: HTMLElement, visible: boolean) {
+  const display = visible ? '' : 'none';
+  if (el.style.display !== display) el.style.display = display;
+}

package/src/components/filter-container/filter-container.test.ts

@@ -1,5 +1,8 @@
 import '../../../dist/zn.min.js';
 import { expect, fixture, html } from '@open-wc/testing';
+import type ZnFilterContainer from './filter-container.component';
+
+const nextFrame = () => new Promise(requestAnimationFrame);
 
 describe('<zn-filter-container>', () => {
   it('should render a component', async () => {
@@ -7,4 +10,26 @@ describe('<zn-filter-container>', () => {
 
     expect(el).to.exist;
   });
+
+  it('hides non-matching items and empty panels', async () => {
+    const el = await fixture<ZnFilterContainer>(html`
+      <zn-filter-container>
+        <zn-panel id="fruit"><div data-filter="Apple"></div><div data-filter="Banana"></div></zn-panel>
+        <zn-panel id="veg"><div data-filter="Carrot"></div></zn-panel>
+      </zn-filter-container>
+    `);
+
+    el.handleSearchChange({target: {value: 'app'}} as unknown as Event);
+    await nextFrame();
+
+    expect(el.querySelector<HTMLElement>('[data-filter="Apple"]')!.style.display).to.equal('');
+    expect(el.querySelector<HTMLElement>('[data-filter="Banana"]')!.style.display).to.equal('none');
+    expect(el.querySelector<HTMLElement>('#fruit')!.style.display).to.equal('');
+    expect(el.querySelector<HTMLElement>('#veg')!.style.display).to.equal('none');
+
+    el.handleSearchChange({target: {value: ''}} as unknown as Event);
+    await nextFrame();
+
+    expect(el.querySelector<HTMLElement>('#veg')!.style.display).to.equal('');
+  });
 });

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

@@ -2,6 +2,7 @@ import {classMap} from 'lit/directives/class-map.js';
 import {type CSSResultGroup, html, type PropertyValues, unsafeCSS} from 'lit';
 import {HasSlotController} from '../../internal/slot';
 import {property, state} from 'lit/decorators.js';
+import {tabContainerSelector} from '../tabs/tabs.component';
 import ZnButton from '../button';
 import ZnCopyButton from '../copy-button';
 import ZnExpandingAction from '../expanding-action';
@@ -30,6 +31,7 @@ interface TabDefinition {
  * @since 1.0
  *
  * @slot - Page content. Use zn-tab for named tabs and header-action/header-actions for header actions.
+ *   Clicking an element in the content with `tab="<tab id>"` opens that tab.
  * @slot description - Rich subtitle/description content. Falls back to the `summary` attribute when empty.
  * @slot bottom - Content rendered below the navbar row (e.g. chips, filters). Forwarded to the navbar's bottom slot.
  */
@@ -68,6 +70,7 @@ export default class ZnPage extends ZnTabs {
     const connected = super.connectedCallback();
     window.addEventListener('alt-press', this.handleAltPress);
     window.addEventListener('alt-up', this.handleAltUp);
+    this.addEventListener('click', this.handleContentTabClick);
     this.prepareTabs();
     this.refreshExpandingActionsState();
     this.tabObserver = new MutationObserver((mutations) => {
@@ -90,6 +93,7 @@ export default class ZnPage extends ZnTabs {
     super.disconnectedCallback();
     window.removeEventListener('alt-press', this.handleAltPress);
     window.removeEventListener('alt-up', this.handleAltUp);
+    this.removeEventListener('click', this.handleContentTabClick);
     this.tabObserver?.disconnect();
     this.tabObserver = null;
     this.actionObserver?.disconnect();
@@ -280,6 +284,23 @@ export default class ZnPage extends ZnTabs {
     }
   }
 
+  // Only elements whose nearest tab container is this page count, so links inside a nested
+  // zn-tabs or zn-page drive that container instead.
+  private handleContentTabClick = (event: MouseEvent) => {
+    const link = event.composedPath().find((node): node is HTMLElement =>
+      node instanceof HTMLElement && node.hasAttribute('tab') && node.closest(tabContainerSelector) === this
+    );
+    if (!link || link.hasAttribute('disabled')) {
+      return;
+    }
+
+    const definition = this.tabDefinitions.find(tab => tab.id === link.getAttribute('tab'));
+    if (definition) {
+      event.preventDefault();
+      this.activateTabDefinition(definition, true, true);
+    }
+  };
+
   private handleNavigationSelect(event: ZnSelectEvent) {
     const item = event.detail.item as HTMLElement;
     if (this.getNavigationItemPage(item) !== this) {
@@ -383,16 +404,16 @@ export default class ZnPage extends ZnTabs {
     return this.pageHistoryKey;
   }
 
-  private activateTabDefinition(tab: TabDefinition, store = false) {
+  private activateTabDefinition(tab: TabDefinition, store = false, pushHistory = false) {
     if (tab.uri) {
       const navItem = this.findNavItemForUri(tab.uri);
       if (navItem) {
-        this.clickTab(navItem, false);
+        this.clickTab(navItem, false, pushHistory);
         this.syncNavigationActive(navItem);
         return;
       }
     }
-    this.activateTab(tab.id, store);
+    this.activateTab(tab.id, store, pushHistory);
   }
 
   private findNavItemForUri(uri: string): HTMLElement | null {

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

@@ -350,6 +350,58 @@ describe('<zn-page>', () => {
     expect(innerDynamicPanel.hasAttribute('selected')).to.equal(true);
   });
 
+  it('opens a tab when an element in the content with a tab attribute is clicked', async () => {
+    const el = await fixture<ZnPage>(html`
+      <zn-page caption="Content Tab Link">
+        <zn-tab caption="Overview" id="overview">
+          <zn-button tab="details">Open details</zn-button>
+          <zn-button tab="details" disabled>Disabled link</zn-button>
+        </zn-tab>
+        <zn-tab caption="Details" id="details">Details Content</zn-tab>
+      </zn-page>
+    `);
+    await aTimeout(40);
+
+    // zn-button.click() skips event dispatch, so click the rendered button as a user would.
+    const [link, disabledLink] = Array.from(el.querySelectorAll('zn-button'))
+      .map(button => button.shadowRoot!.querySelector<HTMLElement>('button')!);
+
+    disabledLink.click();
+    await aTimeout(40);
+    expect(el.getAttribute('active')).to.equal('overview');
+
+    link.click();
+    await aTimeout(40);
+    expect(el.getAttribute('active')).to.equal('details');
+    expect(el.shadowRoot!.querySelector('#details')!.hasAttribute('selected')).to.equal(true);
+    const activeItem = el.shadowRoot!.querySelector<HTMLElement>('zn-navbar li.active');
+    expect(activeItem?.getAttribute('tab')).to.equal('details');
+  });
+
+  it('leaves content tab links inside a nested page to that page', async () => {
+    const outerPage = await fixture<ZnPage>(html`
+      <zn-page caption="Nested Content Tab Link">
+        <zn-tab caption="Outer One" id="outer-one">
+          <zn-page caption="Nested Content Tab Link Inner" nested>
+            <zn-tab caption="Inner One" id="inner-one">
+              <zn-button tab="inner-two">Inner link</zn-button>
+            </zn-tab>
+            <zn-tab caption="Inner Two" id="inner-two">Inner Two Content</zn-tab>
+          </zn-page>
+        </zn-tab>
+        <zn-tab caption="Outer Two" id="inner-two">Outer Two Content</zn-tab>
+      </zn-page>
+    `);
+    await aTimeout(80);
+
+    const innerPage = outerPage.querySelector<ZnPage>('zn-page')!;
+    innerPage.querySelector('zn-button')!.shadowRoot!.querySelector<HTMLElement>('button')!.click();
+    await aTimeout(40);
+
+    expect(innerPage.getAttribute('active')).to.equal('inner-two');
+    expect(outerPage.getAttribute('active')).to.equal('outer-one');
+  });
+
   it('keeps nested page tab selections scoped to the nested page', async () => {
     const outerPage = await fixture<ZnPage>(html`
       <zn-page caption="Outer Page">

package/src/components/tabs/tabs.component.ts

@@ -25,7 +25,7 @@ import styles from './tabs.scss';
 // Every element that manages its own tabs (ZnTabs and its subclasses). Tab
 // registration must stop at these so an outer container never claims a nested
 // container's tabs.
-const tabContainerSelector = 'zn-tabs, zn-page, zn-page-nav';
+export const tabContainerSelector = 'zn-tabs, zn-page, zn-page-nav';
 
 /**
  * @summary Short summary of the component's intended use.