kempo-ui 0.4.26 → 0.4.28

package/docs/utils/formatTimestamp.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/object.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/propConverters.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/sanitizeHtml.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/string.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/theme.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/toTitleCase.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/type.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/voice.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs/utils/wait.html

@@ -228,6 +228,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="../components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="../utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="../utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -360,6 +362,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="../utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="../utils/cookie.html">cookie</a>
         <a href="../utils/context.html">context</a>
         <a href="../utils/debounce.html">debounce</a>

package/docs-src/index.page.html

@@ -319,6 +319,12 @@
 
     <h2>Utils</h2>
     <div class="row -mx">
+      <div class="span-12 t-span-6 d-span-4 px">
+        <a href="{{pathToRoot}}utils/closestAcrossShadow.html" class="card mb no-link d-b">
+          <h3 class="tc-primary">closestAcrossShadow</h3>
+          <p class="tc-muted">closest() that walks past shadow-DOM boundaries to find an ancestor.</p>
+        </a>
+      </div>
       <div class="span-12 t-span-6 d-span-4 px">
         <a href="{{pathToRoot}}utils/cookie.html" class="card mb no-link d-b">
           <h3 class="tc-primary">cookie</h3>

package/docs-src/nav.fragment.html

@@ -212,6 +212,8 @@
           <k-filter-item filter-keywords="button base component keyboard disabled accessibility"><a
               href="{{pathToRoot}}components/button.html"
             >Button<br><small>Base Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="closestAcrossShadow closest shadow dom utils utility"><a
+              href="{{pathToRoot}}utils/closestAcrossShadow.html">closestAcrossShadow<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="cookie utils utility"><a
               href="{{pathToRoot}}utils/cookie.html">cookie<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="context utils utility"><a
@@ -344,6 +346,7 @@
 
       <h5 class="mb0">Utils</h5>
       <div class="pl mb">
+        <a href="{{pathToRoot}}utils/closestAcrossShadow.html">closestAcrossShadow</a>
         <a href="{{pathToRoot}}utils/cookie.html">cookie</a>
         <a href="{{pathToRoot}}utils/context.html">context</a>
         <a href="{{pathToRoot}}utils/debounce.html">debounce</a>

package/docs-src/utils/closestAcrossShadow.page.html

@@ -0,0 +1,49 @@
+<page pageName="closestAcrossShadow" title="closestAcrossShadow - Kempo UI">
+  <content location="header"></content>
+  <content>
+    <h1>closestAcrossShadow</h1>
+    <k-accordion persistent-id="toc" class="b r mb">
+      <k-accordion-header for-panel="toc-panel">Table of Contents</k-accordion-header>
+      <k-accordion-panel name="toc-panel">
+        <div class="m ">
+          <h6>Usage</h6>
+          <a href="#basicUsage">Basic Usage</a><br />
+          <a href="#parameters">Parameters</a><br />
+          <a href="#examples">Examples</a><br />
+        </div>
+      </k-accordion-panel>
+    </k-accordion>
+
+    <h3>Description</h3>
+    <p>The <code>closestAcrossShadow</code> utility works like the native
+      <code>Element.closest()</code>, but it does not stop at shadow-DOM boundaries.
+      When the current tree yields no match it continues from the host of the enclosing
+      shadow root and keeps walking up toward the document, returning the nearest matching
+      ancestor (or the element itself), or <code>null</code> if there is none.</p>
+    <p>This is useful when a component nested inside another component's shadow root needs
+      to locate a shared ancestor — for example a <a href="{{pathToRoot}}components/context.html"><code>k-context</code></a> —
+      which native <code>closest()</code> cannot reach because it never crosses shadow boundaries.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> closestAcrossShadow <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/closestAcrossShadow.js'</span>;<br /><br /><span class="hljs-comment">// From inside a deeply nested component, reach a shared k-context:</span><br /><span class="hljs-keyword">const</span> ctx = closestAcrossShadow(<span class="hljs-keyword">this</span>, <span class="hljs-string">'k-context'</span>);<br /><span class="hljs-keyword">const</span> settings = ctx?.get(<span class="hljs-string">'settings'</span>);</code></pre>
+
+    <h3 id="parameters"><a href="#parameters" class="no-link">Parameters</a></h3>
+    <h5><code>element<i>: Element</i></code></h5>
+    <p>The element to start searching from. The element itself is included in the match, just like <code>closest()</code>.</p>
+    <h5><code>selector<i>: string</i></code></h5>
+    <p>A CSS selector to match ancestors against.</p>
+    <h5><code><i>returns</i>: Element | null</code></h5>
+    <p>The nearest matching ancestor across shadow boundaries, or <code>null</code> if none match.</p>
+
+    <h3 id="examples"><a href="#examples" class="no-link">Examples</a></h3>
+
+    <h4>Reading a context from a nested shadow component</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> closestAcrossShadow <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/closestAcrossShadow.js'</span>;<br /><br />connectedCallback() {<br />  <span class="hljs-keyword">super</span>.connectedCallback();<br />  <span class="hljs-keyword">const</span> ctx = closestAcrossShadow(<span class="hljs-keyword">this</span>, <span class="hljs-string">'k-context'</span>);<br />  ctx?.addEventListener(<span class="hljs-string">'context:set'</span>, () =&gt; <span class="hljs-keyword">this</span>.requestUpdate());<br />}</code></pre>
+
+    <h4>Falls back to null</h4>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// No matching ancestor in any tree:</span><br>closestAcrossShadow(someDetachedNode, <span class="hljs-string">'.missing'</span>); <span class="hljs-comment">// =&gt; null</span></code></pre>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+  </content>
+</page>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-ui",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "type": "module",
   "description": "A Lit based web-component library",
   "main": "index.js",

package/src/utils/closestAcrossShadow.js

@@ -0,0 +1,23 @@
+/*
+  closestAcrossShadow
+
+  Like Element.closest(), but it does not stop at shadow-DOM boundaries. When the
+  current tree yields no match, it continues from the host of the enclosing shadow
+  root and keeps walking up toward the document. Returns the nearest matching
+  ancestor (or the element itself), or null if there is none.
+
+  Useful for components nested inside another component's shadow root that need to
+  locate a shared ancestor — e.g. a k-context — which native closest() can't reach.
+*/
+export const closestAcrossShadow = (element, selector) => {
+  let node = element;
+  while(node){
+    const match = node.closest?.(selector);
+    if(match) return match;
+    const root = node.getRootNode();
+    node = root instanceof ShadowRoot ? root.host : null;
+  }
+  return null;
+};
+
+export default closestAcrossShadow;

package/tests/utils/closestAcrossShadow.browser-test.js

@@ -0,0 +1,90 @@
+import closestAcrossShadow, { closestAcrossShadow as named } from '../../src/utils/closestAcrossShadow.js';
+
+const cleanup = (el) => {
+  if(el && el.parentNode){
+    el.parentNode.removeChild(el);
+  }
+};
+
+export default {
+  'exports the function as default and named export': ({pass, fail}) => {
+    if(typeof closestAcrossShadow === 'function' && typeof named === 'function'){
+      pass('exported correctly as both default and named export');
+    } else {
+      fail('not exported correctly');
+    }
+  },
+
+  'finds an ancestor within the same tree (like closest)': ({pass, fail}) => {
+    const root = document.createElement('div');
+    root.className = 'target';
+    root.innerHTML = '<section><span id="leaf"></span></section>';
+    document.body.appendChild(root);
+    const found = closestAcrossShadow(root.querySelector('#leaf'), '.target');
+    cleanup(root);
+    if(found === root){
+      pass('found ancestor in the same tree');
+    } else {
+      fail('did not find ancestor in the same tree');
+    }
+  },
+
+  'returns the element itself when it matches': ({pass, fail}) => {
+    const el = document.createElement('div');
+    el.className = 'me';
+    document.body.appendChild(el);
+    const found = closestAcrossShadow(el, '.me');
+    cleanup(el);
+    if(found === el){
+      pass('returned the element itself');
+    } else {
+      fail('did not return the element itself');
+    }
+  },
+
+  'crosses a shadow boundary to find an ancestor': ({pass, fail}) => {
+    const host = document.createElement('div');
+    host.className = 'target';
+    document.body.appendChild(host);
+    const inner = document.createElement('span');
+    host.attachShadow({ mode: 'open' }).appendChild(inner);
+    const found = closestAcrossShadow(inner, '.target');
+    cleanup(host);
+    if(found === host){
+      pass('crossed a shadow boundary');
+    } else {
+      fail('did not cross the shadow boundary');
+    }
+  },
+
+  'crosses multiple nested shadow boundaries': ({pass, fail}) => {
+    const host = document.createElement('div');
+    host.className = 'target';
+    document.body.appendChild(host);
+    const mid = document.createElement('div');
+    host.attachShadow({ mode: 'open' }).appendChild(mid);
+    const leaf = document.createElement('span');
+    mid.attachShadow({ mode: 'open' }).appendChild(leaf);
+    const found = closestAcrossShadow(leaf, '.target');
+    cleanup(host);
+    if(found === host){
+      pass('crossed multiple nested shadow boundaries');
+    } else {
+      fail('did not cross multiple nested shadow boundaries');
+    }
+  },
+
+  'returns null when there is no match anywhere': ({pass, fail}) => {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const inner = document.createElement('span');
+    host.attachShadow({ mode: 'open' }).appendChild(inner);
+    const found = closestAcrossShadow(inner, '.nope');
+    cleanup(host);
+    if(found === null){
+      pass('returned null when no match');
+    } else {
+      fail(`expected null, got ${found}`);
+    }
+  }
+};