panelset 0.5.0

package/src/docs/views/events.pug

@@ -0,0 +1,222 @@
+extends /docs/views/templates/layouts/_base
+
+append variables
+	- pagetitle = "Events"
+
+
+block content
+	.lane
+		.container
+			.page-header
+				h1 Events
+				p.lead PanelSet dispatches custom events for activation lifecycle tracking
+				p All events are dispatched from the panelset container element and bubble up the DOM.
+
+	.lane
+		.container
+			h2 Available events and possible uses
+
+			.example.api
+				h3.code.method-signature Event: 'ps:ready'
+				p Fires when the PanelSet is fully initialized
+				h4 Detail:
+				dl
+					dt.code container: HTMLElement
+					dd The container element the PanelSet was initialized on
+					
+					dt.code instance: PanelSet
+					dd The PanelSet instance that was initialized
+				br
+				+codeblock('JavaScript').
+					document.addEventListener('ps:ready', (e) => {
+					  const container = e.detail.container; // or e.target
+					  const instance = e.detail.instance;
+					
+					  // Track which panelset was initialized
+					  analytics.track('PanelSet Initialized', {
+					    id: container.id,
+					    panelCount: instance.panels.length
+					  });
+					});
+				//-
+
+			.example.api.white
+				h3.code.method-signature Event: 'ps:beforeactivate'
+				p Fires before activation begins, can be used for async content loading
+
+				h4 Detail:
+				dl
+					dt.code panelId: string
+					dd ID of the panel being activated
+					
+					dt.code targetPanel: HTMLElement
+					dd The panel element being activated
+					
+					dt.code outgoingPanel: HTMLElement | null
+					dd The panel being deactivated
+					
+					dt.code signal: AbortSignal
+					dd Signal to abort async operations if user clicks away
+					
+					dt.code promise: Promise | null
+					dd Set this to a promise to delay activation until it resolves
+
+				br
+				+codeblock('JavaScript').
+					container.addEventListener('ps:beforeactivate', (e) => {
+					  const { targetPanel, signal } = e.detail;
+					
+					  // Skip if already loaded
+					  if (targetPanel.dataset.loaded === 'true') return;
+					
+					  // Set promise to load content
+					  e.detail.promise = fetch(`/api/panel/${targetPanel.id}`, { signal })
+					    .then(response => response.text())
+					    .then(html => {
+					      targetPanel.innerHTML = html;
+					      targetPanel.dataset.loaded = 'true';
+					    });
+					});
+				//-
+				br
+				p Or use the convenience method:
+				+codeblock('JavaScript').
+					panelSet.onBeforeActivate((targetPanel, signal) => {
+					  return fetch(`/api/panel/${targetPanel.id}`, { signal })
+					    .then(response => response.text())
+					    .then(html => targetPanel.innerHTML = html);
+					}, { once: true }); // Auto-caching
+				//-
+
+			.example.api.white
+				h3.code.method-signature Event: 'ps:activationstart'
+				p Fires before any transitions begin
+				h4 Detail:
+				dl
+					dt.code panelId: string
+					dd ID of the panel being activated
+					
+					dt.code trigger: HTMLElement | null
+					dd The button/element that triggered the activation (if provided)
+				br
+				+codeblock('JavaScript').
+					container.addEventListener('ps:activationstart', (e) => {
+					  console.log('Starting activation:', e.detail.panelId);
+					  console.log('Triggered by:', e.detail.trigger);
+
+					  // Update UI, analytics, etc.
+					  if (e.detail.trigger) {
+					    e.detail.trigger.setAttribute('aria-busy', 'true');
+					  }
+					});
+				//-
+
+
+			.example.api.white
+				h3.code.method-signature Event: 'ps:activationcomplete'
+				p Fires after height and panel transitions complete
+				h4 Detail:
+				dl
+					dt.code panelId: string
+					dd ID of the panel being activated
+					
+					dt.code trigger: HTMLElement | null
+					dd The button/element that triggered the activation (if provided)
+				br
+				+codeblock('JavaScript').
+					container.addEventListener('ps:activationcomplete', (e) => {
+					  console.log('Activation complete:', e.detail.panelId);
+
+					  // Focus management, scroll, analytics
+					  const panel = document.getElementById(e.detail.panelId);
+					  const firstInput = panel.querySelector('input, button');
+					  firstInput?.focus();
+					});
+				//-
+
+
+			.example.api.white
+				h3.code.method-signature Event: 'ps:activationaborted'
+				p Fires if an activation is aborted due to a new activation request
+				h4 Detail:
+				dl
+					dt.code panelId: string
+					dd ID of the panel of which the activation was aborted
+					
+					dt.code trigger: HTMLElement | null
+					dd The button/element that triggered the event
+				br
+				+codeblock('JavaScript').
+					container.addEventListener('ps:activationaborted', (e) => {
+					  console.log('Activation aborted:', e.detail.panelId);
+					
+					  // Cleanup, remove loading states
+					  if (e.detail.trigger) {
+					    e.detail.trigger.setAttribute('aria-busy', 'false');
+					  }
+					});
+				//-
+
+
+append scripts
+	if isProd
+		script(type="module", vite-ignore).
+			import { PanelSet } from '/lib/panelset.js';
+			PanelSet.init();
+	else
+		script(type="module").
+			import { PanelSet } from '/src/lib/index.js';
+			import '/src/lib/styles/panelset.scss';
+			PanelSet.init({debug: true});
+
+	script.
+		let transitionsEnabled = true;
+
+		let closablePanelSet = null;
+		document.addEventListener('panelset:ready', (e) => {
+			const instance = e.detail.instance;
+			const container = e.target;
+			if (container.id == 'config-closable-demo') {
+				closablePanelSet = instance;
+			}
+		})
+
+		document.addEventListener('click', (e) => {
+			const button = e.target.closest('button');
+			if (!button) return;
+
+			if (button.dataset.panel) {
+				const panelId = button.getAttribute('data-panel');
+				const panel = document.getElementById(panelId);
+				const container = panel?.closest('[data-panelset]');
+				
+				if (container?.panelSet) {
+					container.panelSet.setActive(panelId, true, { trigger: button });
+				}
+			}
+		
+			if (button.id == "toggle-transitions") {
+				const transDemo = document.getElementById('config-transitions-demo');
+				if (transDemo?.panelSet.config.transitions == false) {
+					transDemo.panelSet.config.transitions = true;
+					button.textContent = "Disable Transitions";
+				} else {
+					transDemo.panelSet.config.transitions = false;
+					button.textContent = "Enable Transitions";
+				}
+			}
+		});
+
+
+		
+		// Log events
+		document.addEventListener('activationstart', (e) => {
+			console.log('[Demo PanelSet log] Activationstart:', e.detail);
+		});
+		
+		document.addEventListener('activationcomplete', (e) => {
+			console.log('[Demo PanelsSet log] Activationcomplete:', e.detail);
+		});
+
+
+

package/src/docs/views/examples/async.pug

@@ -0,0 +1,268 @@
+extends /docs/views/templates/layouts/_base
+
+append variables
+	- pagetitle = "Async Loading"
+
+block content
+	.lane
+		.container
+			.page-header
+				h1 Async Loading
+				p.lead Load panel content on-demand with promises, fetch, or heavy computation
+
+	.lane
+		.container
+			.title-text
+				h2 Overview
+				p PanelSet supports async content loading through the #[code ps:beforeactivate] event. This allows you to fetch data from APIs, process large datasets, or perform any async operation before a panel becomes visible.
+
+			h3 Key Features
+			ul
+				li Load content only when needed (lazy loading)
+				li Automatic loading spinner with configurable delay
+				li Built-in abort support for cancelled activations
+				li Auto-caching with the #[code once] option
+				li Smooth height transitions after content loads
+
+	.lane
+		.container
+			h2 The onBeforeActivate() Method
+			
+			.title-text
+				p The easiest way to add async loading is with the #[code onBeforeActivate()] convenience method:
+
+			+codeblock('JS').
+				const panelSet = new PanelSet('#my-panelset');
+
+				panelSet.onBeforeActivate((targetPanel, signal) => {
+				  // Return a promise to delay activation
+				  return fetch(`/api/content/${targetPanel.id}`, { signal })
+				    .then(response => response.text())
+				    .then(html => {
+				      targetPanel.innerHTML = html;
+				    });
+				}, { once: true }); // Load once, cache forever
+
+			.example.api
+				h3 Parameters
+				dl
+					dt targetPanel
+					dd The HTMLElement being activated
+					
+					dt signal
+					dd AbortSignal for canceling the operation if user clicks away
+					
+					dt options.once
+					dd If #[code true], content loads only once and is cached. Set to #[code false] to always reload. Default: #[code false]
+
+	.lane
+		.container
+			h2 Live Example: Fetch from API
+			p This example uses a 'slowfetch' to mimic a slow network request to fetch recipe data. The renderRecipe function just formats the data into HTML.
+
+			.example
+				.demo
+					.demo-controls
+						button(data-panel="async-panel-1") Panel 1 (Static)
+						button(data-panel="async-panel-2") Panel 2 (Fetch Recipe)
+						button(data-panel="async-panel-3") Panel 3 (Static)
+					
+					#async-demo(data-panelset data-empty-panel-height="300" data-loading-delay="200")
+						.panel-wrapper
+							#async-panel-1(role="tabpanel" class="active" data-loaded="true")
+								h3 Static Content
+								p This panel has pre-loaded content.
+							
+							#async-panel-2(role="tabpanel" hidden)
+								// Empty - will load async
+							
+							#async-panel-3(role="tabpanel" hidden)
+								h3 Another Static Panel
+								p More pre-loaded content.
+
+				+codeblock('JS').
+					asyncPanelSet.onBeforeActivate((targetPanel, signal) => {
+					    if (targetPanel.id === 'async-panel-2') {
+					        return slowfetch(`https://dummyjson.com/recipes/${randomIntFromInterval(1, 10)}`, { signal })
+					            .then(response => response.json())
+					            .then(data => {
+					                targetPanel.innerHTML = renderRecipe(data);
+					            });
+					    }
+					});
+
+	.lane
+		.container
+			h2 Example: Heavy Computation
+
+			.title-text
+				p You can also use async loading for CPU-intensive operations:
+
+			+codeblock('JS').
+				panelSet.onBeforeActivate((targetPanel, signal) => {
+				  if (targetPanel.id === 'heavy-calc') {
+				    return new Promise((resolve) => {
+				      // Simulate heavy calculation
+				      setTimeout(() => {
+				        const result = fibonacci(40); // Actually slow!
+				        targetPanel.innerHTML = `
+				          <h3>Calculation Complete</h3>
+				          <p>Fibonacci(40) = ${result}</p>
+				        `;
+				        resolve();
+				      }, 2000);
+				    });
+				  }
+				});
+
+				function fibonacci(n) {
+				  if (n <= 1) return n;
+				  return fibonacci(n - 1) + fibonacci(n - 2);
+				}
+
+	.lane
+		.container
+			.title-text
+				h2 Using the Event Directly
+				p For more control, listen to the #[code ps:beforeactivate] event directly:
+
+			+codeblock('JS').
+				container.addEventListener('ps:beforeactivate', (e) => {
+				  const { panelId, targetPanel, signal } = e.detail;
+				  
+				  // Skip if already loaded
+				  if (targetPanel.dataset.loaded === 'true') return;
+				  
+				  // Set the promise property to delay activation
+				  e.detail.promise = fetch(`/api/panel/${panelId}`, { signal })
+				    .then(response => response.text())
+				    .then(html => {
+				      targetPanel.innerHTML = html;
+				      targetPanel.dataset.loaded = 'true';
+				    });
+				});
+
+			.example.api
+				h3 Event Detail Properties
+				dl
+					dt panelId
+					dd String - ID of the panel being activated
+					
+					dt targetPanel
+					dd HTMLElement - The panel element
+					
+					dt outgoingPanel
+					dd HTMLElement | null - The panel being deactivated
+					
+					dt signal
+					dd AbortSignal - Use with fetch to cancel if user clicks away
+					
+					dt promise
+					dd Promise | null - Set this to delay activation until it resolves
+
+	.lane
+		.container
+			h2 Loading States
+
+			.title-text
+				h3 Loading Spinner
+				p During async operations, PanelSet shows a loading spinner. Configure the delay to prevent flashing on fast connections:
+
+			+codeblock('JS').
+				const panelSet = new PanelSet('#my-panelset', {
+				  loadingDelay: 300  // Wait 300ms before showing spinner
+				});
+
+			.title-text
+				p Or via data attribute:
+
+			+codeblock('HTML').
+				<div data-panelset data-loading-delay="300">
+
+			.title-text
+				h3 Empty Panel Height
+				p Set a minimum height during loading (shows spinner in that space):
+
+			+codeblock('JS').
+				const panelSet = new PanelSet('#my-panelset', {
+				  emptyPanelHeight: 200  // 200px minimum during load
+				});
+
+	.lane
+		.container
+			h2 Abort Handling
+
+			.title-text
+				p When users click away during loading, the operation is automatically aborted via the AbortSignal:
+
+			+codeblock('JS').
+				panelSet.onBeforeActivate((targetPanel, signal) => {
+				  // Pass signal to fetch - automatically cancels on abort
+				  return fetch('/api/data', { signal })
+				    .then(/* ... */);
+				});
+
+			.title-text
+				p The #[code ps:activationaborted] event fires when an async load is cancelled:
+
+			+codeblock('JS').
+				container.addEventListener('ps:activationaborted', (e) => {
+				  console.log('Load cancelled:', e.detail.panelId);
+				  // Clean up, show message, etc.
+				});
+
+	.lane
+		.container
+			h2 Complete Example
+
+			+codeblock('JS').
+				import { PanelSet } from 'panelset';
+				import 'panelset/dist/panelset.css';
+
+				const panelSet = new PanelSet('#my-panelset', {
+				  emptyPanelHeight: 300,
+				  loadingDelay: 200
+				});
+
+				// Async loading with error handling
+				panelSet.onBeforeActivate((targetPanel, signal) => {
+				  if (targetPanel.id === 'async-content') {
+				    return fetch('/api/content', { signal })
+				      .then(response => {
+				        if (!response.ok) throw new Error('Load failed');
+				        return response.json();
+				      })
+				      .then(data => {
+				        targetPanel.innerHTML = renderContent(data);
+				      })
+				      .catch(error => {
+				        if (error.name === 'AbortError') return; // User clicked away
+				        targetPanel.innerHTML = `<p class="error">Failed to load content</p>`;
+				      });
+				  }
+				}, { once: true });
+
+				// Event listeners
+				panelSet.element.addEventListener('ps:activationaborted', (e) => {
+				  console.log('Cancelled:', e.detail.panelId);
+				});
+
+				panelSet.element.addEventListener('ps:activationcomplete', (e) => {
+				  console.log('Complete:', e.detail.panelId);
+				});
+
+append scripts
+	if isProd
+		script(type="module", vite-ignore).
+			import { PanelSet } from '/lib/panelset.js';
+			PanelSet.init({debug: true});
+	else
+		script(type="module").
+			import { PanelSet } from '/src/lib/index.js';
+			import '/src/lib/styles/panelset.scss';
+			PanelSet.init({debug: true});
+
+	if isProd
+		script(src="/assets/scripts/examples/async.js" type="module" vite-ignore)
+	else
+		script(type="module" src="/src/docs/assets/scripts/example-async.js")

package/src/docs/views/examples/basic.pug

@@ -0,0 +1,155 @@
+extends /docs/views/templates/layouts/_base
+
+append variables
+	- pagetitle = "Basic tabs"
+
+
+block content
+	.lane
+		.container
+			.page-header
+				h1 Basic tabs example
+				p.lead The most common use case - a simple tabbed interface
+
+	.lane
+		.container
+			h2 Live demo
+
+			.example
+
+				.demo
+					nav.tabs(role="tablist" aria-label="Content sections")
+						button(role="tab" aria-controls="demo-panel-1" aria-selected="true") Features
+						button(role="tab" aria-controls="demo-panel-2") Pricing
+						button(role="tab" aria-controls="demo-panel-3") Support
+
+					+examplepanelset('demo').tab-content
+
+
+				+codeblock('HTML')
+					+examplepanelset('demo').tab-content
+
+				+codeblock('JavaScript').
+					const tabs = document.querySelectorAll('[role="tab"]');
+					
+					document.addEventListener('click', (e) => {
+					  const button = e.target.closest('button');
+					  if (!button) return;
+
+					  if (button.hasAttribute('aria-controls')) {
+					    const panelId = button.getAttribute('aria-controls');
+					    const panel = document.getElementById(panelId);
+					    const container = panel?.closest('[data-panelset]');
+					
+					    if (container?.panelSet) {
+					      container.panelSet.setActive(panelId, true, { trigger: button });
+					    }
+					  }
+					});
+
+					// Update ARIA states
+					document.addEventListener('ps:activationstart', (e) => {
+					  tabs.forEach(tab => {
+					    const isActive = tab.getAttribute('aria-controls') === e.detail.panelId;
+					    tab.setAttribute('aria-selected', isActive);
+					  });
+					});
+
+
+	.lane
+		.container
+			h2 Accessibility features
+			p PanelSet is built with accessibility in mind, but because it provides low-level functionality, there are only a few of them built in: 
+			ul
+				li
+					strong ARIA roles: 
+					| Uses #[code role='tabpanel']. This is used internally to find the panels.
+				li
+					strong Hidden attribute: 
+					| Properly hides inactive panels from screen readers
+
+			p Beyond that it's up to you to implement proper ARIA roles and attributes in your markup, like linking the button and panel ID's with aria. Futhermore, PanelSet does not manage focus or keyboard shortcuts like arrow keys support for you, so you'll need to handle that as appropriate for your use case.
+
+append scripts
+	if isProd
+		script(type="module", vite-ignore).
+			import { PanelSet } from '/lib/panelset.js';
+			PanelSet.init();
+	else
+		script(type="module").
+			import { PanelSet } from '/src/lib/index.js';
+			import '/src/lib/styles/panelset.scss';
+			PanelSet.init({debug: true});
+
+	script.
+		const tabs = document.querySelectorAll('[role="tab"]');
+		
+		document.addEventListener('click', (e) => {
+			const button = e.target.closest('button');
+			if (!button) return;
+
+			if (button.hasAttribute('aria-controls')) {
+				const panelId = button.getAttribute('aria-controls');
+				const panel = document.getElementById(panelId);
+				const container = panel?.closest('[data-panelset]');
+				
+				if (container?.panelSet) {
+					container.panelSet.show(panelId, true, { trigger: button });
+				}
+			}
+		});
+
+		// Update ARIA states
+		document.addEventListener('ps:activationstart', (e) => {
+			tabs.forEach(tab => {
+				const isActive = tab.getAttribute('aria-controls') === e.detail.panelId;
+				tab.setAttribute('aria-selected', isActive);
+			});
+		});
+
+
+
+append styles
+	style.
+		/* Tab-specific styles for this example */
+		//- #basic-tabs {
+		//- 	--fadeout-speed: 0.5s;
+		//- 	--fadein-speed: 0.5s;
+		//- 	--fadein-delay: 0.25s;
+		//- }
+		.tabs {
+			padding: 0 0.5rem;
+			display: flex;
+			//- gap: 0.5rem;
+			margin-bottom: 2px;
+		}
+		
+		.tabs button {
+			background: transparent;
+			border: none;
+			border-bottom: 3px solid transparent;
+			padding: 0.75rem 1.5rem;
+			font-size: 1rem;
+			font-weight: 500;
+			color: #6b7280;
+			cursor: pointer;
+			transition: all 0.2s;
+			margin-bottom: -2px;
+		}
+		
+		.tabs button:hover {
+			color: #3b82f6;
+			background: #f9fafb;
+		}
+		
+		.tabs button[aria-selected="true"] {
+			color: #3b82f6;
+			border-bottom-color: #3b82f6;
+		}
+		
+		.tab-content {
+			padding: 1.5rem;
+			background: white;
+			border: 1px solid #e5e7eb;
+			border-radius: 6px;
+		}