@brightspot/ui 1.3.0 → 1.4.1

package/dist/storybook/assets/onRemove.stories-C3FcxtYh.js

@@ -0,0 +1,234 @@
+import{x as p}from"./iframe-Bl9oHz5c.js";import"./preload-helper-PPVm8Dsz.js";let l=!1;function m(e,o){const s=new MutationObserver(r=>{for(const v of r)for(const n of v.removedNodes)n.contains(e)&&!l&&(s.disconnect(),o())});s.observe(document,{childList:!0,subtree:!0})}m.pause=()=>{l=!0};m.resume=()=>{l=!1};const b={title:"Utilities/onRemove",tags:["autodocs"],parameters:{docs:{subtitle:"The `onRemove` utility triggers a callback when a DOM element is removed from the document. Uses MutationObserver to watch for removals, with global pause/resume support."},controls:{expanded:!0}},argTypes:{selector:{control:{type:"text"},description:"CSS selector of element to watch"}},args:{selector:".watched-item"}},i={render:()=>{const e=`onremove-${Math.random().toString(36).substring(2,9)}`;let o=0,s=0;const r=()=>{const n=document.getElementById(`${e}-items-count`),t=document.getElementById(`${e}-removed-count`);n&&(n.textContent=String(o)),t&&(t.textContent=String(s))};return p`
+      <div class="space-y-4">
+        <div class="text-base">
+          <p class="mb-2">
+            Click "Add Item" to create elements, then click "Remove" on each item. The onRemove callback detects
+            removals and logs them.
+          </p>
+        </div>
+
+        <div class="flex gap-2">
+          <button @click=${()=>{o++;const n=document.getElementById(`${e}-container`);if(!n)return;const t=document.createElement("div"),u=o;t.className="flex items-center justify-between rounded border bg-white p-4",t.innerHTML=`<span>Item ${u}</span>`;const d=document.createElement("button");d.className="rounded bg-red-100 px-2 py-1 text-xs text-red-700 hover:bg-red-200",d.textContent="Remove",d.addEventListener("click",()=>t.remove()),t.appendChild(d),n.appendChild(t),m(t,()=>{s++,o--,r();const g=document.getElementById(`${e}-log`);if(g){const c=document.createElement("div");c.className="text-sm text-gray-600",c.textContent=`Item ${u} removed at ${new Date().toLocaleTimeString()}`,g.prepend(c)}}),r()}} class="bg-primary-500 hover:bg-primary-600 rounded px-4 py-2 text-white">
+            Add Item
+          </button>
+        </div>
+
+        <div id="${e}-container" class="min-h-32 space-y-2 rounded border-2 border-gray-300 bg-gray-50 p-4">
+          <div class="text-sm text-gray-500">Items will appear here...</div>
+        </div>
+
+        <div class="flex justify-around">
+          <div>
+            <div class="text-xs text-gray-500">Active items</div>
+            <div id="${e}-items-count" class="text-2xl font-bold text-gray-900">0</div>
+          </div>
+          <div>
+            <div class="text-xs text-gray-500">Removals detected</div>
+            <div id="${e}-removed-count" class="text-primary-600 text-2xl font-bold">0</div>
+          </div>
+        </div>
+
+        <div>
+          <h4 class="mb-1 text-xs font-bold text-gray-500">Removal Log</h4>
+          <div id="${e}-log" class="max-h-32 overflow-y-auto rounded border border-gray-200 bg-gray-50 p-2">
+            <div class="text-sm text-gray-400">No removals yet.</div>
+          </div>
+        </div>
+      </div>
+    `},parameters:{docs:{description:{story:"Interactive example showing onRemove detecting when elements are removed from the DOM. Add items, then remove them to see the callback fire."}}}},a={render:()=>p`
+    <div class="space-y-4 text-sm">
+      <div>
+        <h3 class="mb-2 font-bold">Basic Usage</h3>
+        <pre
+          class="overflow-x-auto rounded bg-gray-900 p-4 text-gray-100"
+        ><code>import onRemove from '@brightspot/ui/util/onRemove.js'
+
+// Clean up when element is removed
+const widget = document.querySelector('.my-widget')
+onRemove(widget, () => {
+  console.log('Widget was removed')
+  // Tear down event listeners, intervals, etc.
+})</code></pre>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Pause and Resume</h3>
+        <pre class="overflow-x-auto rounded bg-gray-900 p-4 text-gray-100"><code>// Pause during bulk DOM operations
+onRemove.pause()
+
+// Move elements around without triggering callbacks
+container.innerHTML = ''
+container.append(...reorderedElements)
+
+// Resume watching
+onRemove.resume()</code></pre>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Common Use Cases</h3>
+        <ul class="list-inside list-disc space-y-1 text-gray-700">
+          <li>Cleaning up event listeners when elements are removed</li>
+          <li>Cancelling intervals or timeouts tied to DOM elements</li>
+          <li>Disconnecting observers or WebSocket connections</li>
+          <li>Releasing resources when components are destroyed</li>
+        </ul>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Parameters</h3>
+        <ul class="space-y-2">
+          <li><code class="rounded bg-gray-200 px-1">element</code> (Element): The DOM element to watch for removal</li>
+          <li>
+            <code class="rounded bg-gray-200 px-1">callback</code> (function): Called once when the element is removed
+            from the document
+          </li>
+        </ul>
+      </div>
+    </div>
+  `,parameters:{docs:{description:{story:"Code examples and documentation for using the onRemove utility."}}}};i.parameters={...i.parameters,docs:{...i.parameters?.docs,source:{originalSource:`{
+  render: () => {
+    const instanceId = \`onremove-\${Math.random().toString(36).substring(2, 9)}\`;
+    let itemCount = 0;
+    let removeCount = 0;
+    const updateCounts = () => {
+      const itemsEl = document.getElementById(\`\${instanceId}-items-count\`);
+      const removedEl = document.getElementById(\`\${instanceId}-removed-count\`);
+      if (itemsEl) itemsEl.textContent = String(itemCount);
+      if (removedEl) removedEl.textContent = String(removeCount);
+    };
+    const addItem = () => {
+      itemCount++;
+      const container = document.getElementById(\`\${instanceId}-container\`);
+      if (!container) return;
+      const item = document.createElement('div');
+      const itemNum = itemCount;
+      item.className = 'flex items-center justify-between rounded border bg-white p-4';
+      item.innerHTML = \`<span>Item \${itemNum}</span>\`;
+      const removeBtn = document.createElement('button');
+      removeBtn.className = 'rounded bg-red-100 px-2 py-1 text-xs text-red-700 hover:bg-red-200';
+      removeBtn.textContent = 'Remove';
+      removeBtn.addEventListener('click', () => item.remove());
+      item.appendChild(removeBtn);
+      container.appendChild(item);
+
+      // Watch for this element's removal
+      onRemove(item, () => {
+        removeCount++;
+        itemCount--;
+        updateCounts();
+        const log = document.getElementById(\`\${instanceId}-log\`);
+        if (log) {
+          const entry = document.createElement('div');
+          entry.className = 'text-sm text-gray-600';
+          entry.textContent = \`Item \${itemNum} removed at \${new Date().toLocaleTimeString()}\`;
+          log.prepend(entry);
+        }
+      });
+      updateCounts();
+    };
+    return html\`
+      <div class="space-y-4">
+        <div class="text-base">
+          <p class="mb-2">
+            Click "Add Item" to create elements, then click "Remove" on each item. The onRemove callback detects
+            removals and logs them.
+          </p>
+        </div>
+
+        <div class="flex gap-2">
+          <button @click=\${addItem} class="bg-primary-500 hover:bg-primary-600 rounded px-4 py-2 text-white">
+            Add Item
+          </button>
+        </div>
+
+        <div id="\${instanceId}-container" class="min-h-32 space-y-2 rounded border-2 border-gray-300 bg-gray-50 p-4">
+          <div class="text-sm text-gray-500">Items will appear here...</div>
+        </div>
+
+        <div class="flex justify-around">
+          <div>
+            <div class="text-xs text-gray-500">Active items</div>
+            <div id="\${instanceId}-items-count" class="text-2xl font-bold text-gray-900">0</div>
+          </div>
+          <div>
+            <div class="text-xs text-gray-500">Removals detected</div>
+            <div id="\${instanceId}-removed-count" class="text-primary-600 text-2xl font-bold">0</div>
+          </div>
+        </div>
+
+        <div>
+          <h4 class="mb-1 text-xs font-bold text-gray-500">Removal Log</h4>
+          <div id="\${instanceId}-log" class="max-h-32 overflow-y-auto rounded border border-gray-200 bg-gray-50 p-2">
+            <div class="text-sm text-gray-400">No removals yet.</div>
+          </div>
+        </div>
+      </div>
+    \`;
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: \`Interactive example showing onRemove detecting when elements are removed from the DOM. Add items, then remove them to see the callback fire.\`
+      }
+    }
+  }
+}`,...i.parameters?.docs?.source}}};a.parameters={...a.parameters,docs:{...a.parameters?.docs,source:{originalSource:`{
+  render: () => html\`
+    <div class="space-y-4 text-sm">
+      <div>
+        <h3 class="mb-2 font-bold">Basic Usage</h3>
+        <pre
+          class="overflow-x-auto rounded bg-gray-900 p-4 text-gray-100"
+        ><code>import onRemove from '@brightspot/ui/util/onRemove.js'
+
+// Clean up when element is removed
+const widget = document.querySelector('.my-widget')
+onRemove(widget, () => {
+  console.log('Widget was removed')
+  // Tear down event listeners, intervals, etc.
+})</code></pre>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Pause and Resume</h3>
+        <pre class="overflow-x-auto rounded bg-gray-900 p-4 text-gray-100"><code>// Pause during bulk DOM operations
+onRemove.pause()
+
+// Move elements around without triggering callbacks
+container.innerHTML = ''
+container.append(...reorderedElements)
+
+// Resume watching
+onRemove.resume()</code></pre>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Common Use Cases</h3>
+        <ul class="list-inside list-disc space-y-1 text-gray-700">
+          <li>Cleaning up event listeners when elements are removed</li>
+          <li>Cancelling intervals or timeouts tied to DOM elements</li>
+          <li>Disconnecting observers or WebSocket connections</li>
+          <li>Releasing resources when components are destroyed</li>
+        </ul>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Parameters</h3>
+        <ul class="space-y-2">
+          <li><code class="rounded bg-gray-200 px-1">element</code> (Element): The DOM element to watch for removal</li>
+          <li>
+            <code class="rounded bg-gray-200 px-1">callback</code> (function): Called once when the element is removed
+            from the document
+          </li>
+        </ul>
+      </div>
+    </div>
+  \`,
+  parameters: {
+    docs: {
+      description: {
+        story: \`Code examples and documentation for using the onRemove utility.\`
+      }
+    }
+  }
+}`,...a.parameters?.docs?.source}}};const y=["Interactive","UsageExample"];export{i as Interactive,a as UsageExample,y as __namedExportsOrder,b as default};

package/dist/storybook/assets/onVisible.stories-B8Zyu0Th.js

@@ -0,0 +1,187 @@
+import{x as d}from"./iframe-Bl9oHz5c.js";import{o as g}from"./onFind-DqriYjEB.js";import"./preload-helper-PPVm8Dsz.js";import"./_commonjsHelpers-CqkleIqs.js";const b=Symbol.for("brightspot.onVisible");let t;function v(){return t||(t=globalThis[b],t||(t={calledIndex:0},globalThis[b]=t),t)}function h(i,r){const s=`_ovc${v().calledIndex++}`,n=new IntersectionObserver(e=>{for(const o of e)if(o.isIntersecting){const c=o.target,m=c.classList;m.contains(s)||(m.add(s),n.unobserve(c),r(c))}});g(i,e=>{n.observe(e)})}const x={title:"Utilities/onVisible",tags:["autodocs"],parameters:{docs:{subtitle:"The `onVisible` utility triggers a callback once when elements matching a selector become visible in the viewport. Combines `onFind` with `IntersectionObserver` for lazy initialization of dynamically added elements."},controls:{expanded:!0}},argTypes:{selector:{control:{type:"text"},description:"CSS selector to watch for visibility"}},args:{selector:".lazy-item"}},l={render:()=>{const i=`onvisible-${Math.random().toString(36).substring(2,9)}`,r=`.lazy-item-${i}`;let s=0;const n=()=>{const e=document.getElementById(`${i}-visible-count`);e&&(e.textContent=String(s))};return h(r,e=>{s++,n(),e.classList.remove("opacity-30"),e.classList.add("ring-2","ring-success-500","opacity-100"),e.textContent+=" — visible!"}),d`
+      <div class="space-y-4">
+        <div class="text-base">
+          <p class="mb-2">
+            Scroll down inside the box below. Items start faded and are highlighted when they enter the viewport. Each
+            callback fires only once per element.
+          </p>
+        </div>
+
+        <div class="flex justify-around">
+          <div>
+            <div class="text-xs text-gray-500">Items detected as visible</div>
+            <div id="${i}-visible-count" class="text-primary-600 text-2xl font-bold">0</div>
+          </div>
+        </div>
+
+        <div class="h-64 overflow-y-scroll rounded border-2 border-gray-300 bg-gray-50 p-4">
+          <div class="space-y-4">
+            ${Array.from({length:30},(e,o)=>d`<div class="${`lazy-item-${i}`} rounded border bg-white p-4 opacity-30 transition-all">
+                  Item ${o+1}
+                </div>`)}
+          </div>
+        </div>
+      </div>
+    `},parameters:{docs:{description:{story:"Interactive example showing onVisible detecting elements as they scroll into view. Elements are highlighted once when they become visible."}}}},a={render:()=>d`
+    <div class="space-y-4 text-sm">
+      <div>
+        <h3 class="mb-2 font-bold">Basic Usage</h3>
+        <pre
+          class="overflow-x-auto rounded bg-gray-900 p-4 text-gray-100"
+        ><code>import { onVisible } from '@brightspot/ui/util/onVisible.js'
+
+// Lazy-load images when they scroll into view
+onVisible('.lazy-image', (element) => {
+  element.src = element.dataset.src
+})
+
+// Initialize heavy components only when visible
+onVisible('.chart-container', (element) => {
+  initChart(element)
+})</code></pre>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">How It Works</h3>
+        <p class="text-gray-700">
+          onVisible combines two utilities: <code class="rounded bg-gray-200 px-1">onFind</code> detects when matching
+          elements are added to the DOM, then <code class="rounded bg-gray-200 px-1">IntersectionObserver</code> watches
+          for when those elements enter the viewport. The callback fires at most once per element.
+        </p>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Common Use Cases</h3>
+        <ul class="list-inside list-disc space-y-1 text-gray-700">
+          <li>Lazy-loading images or iframes</li>
+          <li>Deferring expensive component initialization</li>
+          <li>Triggering animations on scroll</li>
+          <li>Analytics tracking for element impressions</li>
+        </ul>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Parameters</h3>
+        <ul class="space-y-2">
+          <li>
+            <code class="rounded bg-gray-200 px-1">selectors</code> (string | string[]): CSS selector(s) to watch for
+          </li>
+          <li>
+            <code class="rounded bg-gray-200 px-1">callback</code> (function): Called once per element when it becomes
+            visible
+          </li>
+        </ul>
+      </div>
+    </div>
+  `,parameters:{docs:{description:{story:"Code examples and documentation for using the onVisible utility."}}}};l.parameters={...l.parameters,docs:{...l.parameters?.docs,source:{originalSource:`{
+  render: () => {
+    const instanceId = \`onvisible-\${Math.random().toString(36).substring(2, 9)}\`;
+    const uniqueSelector = \`.lazy-item-\${instanceId}\`;
+    let visibleCount = 0;
+    const updateCount = () => {
+      const el = document.getElementById(\`\${instanceId}-visible-count\`);
+      if (el) el.textContent = String(visibleCount);
+    };
+    onVisible(uniqueSelector, (element: HTMLElement) => {
+      visibleCount++;
+      updateCount();
+      element.classList.remove('opacity-30');
+      element.classList.add('ring-2', 'ring-success-500', 'opacity-100');
+      element.textContent += ' — visible!';
+    });
+    return html\`
+      <div class="space-y-4">
+        <div class="text-base">
+          <p class="mb-2">
+            Scroll down inside the box below. Items start faded and are highlighted when they enter the viewport. Each
+            callback fires only once per element.
+          </p>
+        </div>
+
+        <div class="flex justify-around">
+          <div>
+            <div class="text-xs text-gray-500">Items detected as visible</div>
+            <div id="\${instanceId}-visible-count" class="text-primary-600 text-2xl font-bold">0</div>
+          </div>
+        </div>
+
+        <div class="h-64 overflow-y-scroll rounded border-2 border-gray-300 bg-gray-50 p-4">
+          <div class="space-y-4">
+            \${Array.from({
+      length: 30
+    }, (_, i) => html\`<div class="\${\`lazy-item-\${instanceId}\`} rounded border bg-white p-4 opacity-30 transition-all">
+                  Item \${i + 1}
+                </div>\`)}
+          </div>
+        </div>
+      </div>
+    \`;
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: \`Interactive example showing onVisible detecting elements as they scroll into view. Elements are highlighted once when they become visible.\`
+      }
+    }
+  }
+}`,...l.parameters?.docs?.source}}};a.parameters={...a.parameters,docs:{...a.parameters?.docs,source:{originalSource:`{
+  render: () => html\`
+    <div class="space-y-4 text-sm">
+      <div>
+        <h3 class="mb-2 font-bold">Basic Usage</h3>
+        <pre
+          class="overflow-x-auto rounded bg-gray-900 p-4 text-gray-100"
+        ><code>import { onVisible } from '@brightspot/ui/util/onVisible.js'
+
+// Lazy-load images when they scroll into view
+onVisible('.lazy-image', (element) => {
+  element.src = element.dataset.src
+})
+
+// Initialize heavy components only when visible
+onVisible('.chart-container', (element) => {
+  initChart(element)
+})</code></pre>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">How It Works</h3>
+        <p class="text-gray-700">
+          onVisible combines two utilities: <code class="rounded bg-gray-200 px-1">onFind</code> detects when matching
+          elements are added to the DOM, then <code class="rounded bg-gray-200 px-1">IntersectionObserver</code> watches
+          for when those elements enter the viewport. The callback fires at most once per element.
+        </p>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Common Use Cases</h3>
+        <ul class="list-inside list-disc space-y-1 text-gray-700">
+          <li>Lazy-loading images or iframes</li>
+          <li>Deferring expensive component initialization</li>
+          <li>Triggering animations on scroll</li>
+          <li>Analytics tracking for element impressions</li>
+        </ul>
+      </div>
+
+      <div>
+        <h3 class="mb-2 font-bold">Parameters</h3>
+        <ul class="space-y-2">
+          <li>
+            <code class="rounded bg-gray-200 px-1">selectors</code> (string | string[]): CSS selector(s) to watch for
+          </li>
+          <li>
+            <code class="rounded bg-gray-200 px-1">callback</code> (function): Called once per element when it becomes
+            visible
+          </li>
+        </ul>
+      </div>
+    </div>
+  \`,
+  parameters: {
+    docs: {
+      description: {
+        story: \`Code examples and documentation for using the onVisible utility.\`
+      }
+    }
+  }
+}`,...a.parameters?.docs?.source}}};const w=["Interactive","UsageExample"];export{l as Interactive,a as UsageExample,w as __namedExportsOrder,x as default};