panelset 0.5.0

package/src/docs/views/api-reference.pug

@@ -0,0 +1,474 @@
+extends /docs/views/templates/layouts/_base
+
+append variables
+	- pagetitle = "API reference"
+
+
+block content
+	.lane
+		.container
+			.page-header
+				h1 API reference
+				p.lead Complete reference for PanelSet Lite methods, properties, and static methods
+
+
+	.lane
+		.container
+			h2 Constructor
+
+
+			.example.api
+				h3.code new PanelSet(selector: string | HTMLElement, options?: PanelSetLiteConfig)
+				p Creates a new PanelSet instance.
+				h4 Parameters:
+				dl
+					dt.code selector
+					dd CSS selector string or HTMLElement reference to the panelset container
+					
+					dt.code options (optional)
+					dd Configuration object (see #[a(href="configuration.html") Configuration] page for details)
+				br
+				+codeblock('JavaScript').
+					// With selector string
+					const panelSet = new PanelSet('#my-panelset');
+
+					// With element reference
+					const container = document.getElementById('my-panelset');
+					const panelSet = new PanelSet(container, {
+					  transitions: true,
+					  closable: false,
+					  debug: false
+					});
+				//-
+
+
+
+
+
+
+	.lane
+		.container
+			h2 Instance methods
+				
+
+			.example.api
+				h3.code show(panelId: string, transition?: boolean, options?: ActivationOptions): Promise<void>
+
+				p Activates a panel by ID.
+
+				h4 Parameters:
+				dl
+					dt.code panelId
+					dd ID of the panel to activate
+					
+					dt.code transition (optional)
+					dd Whether to animate the transition. Default: <code>true</code>
+					
+					dt.code options (optional)
+					dd Object with optional <code>trigger</code> property (HTMLElement that triggered activation)
+
+				h4 Returns:
+				p Promise that resolves when activation completes
+
+				br
+				+codeblock('JavaScript').
+					// Basic usage
+					panelSet.show('panel-2');
+					
+					// Without transition
+					panelSet.show('panel-2', false);
+					
+					// With trigger tracking
+					button.addEventListener('click', () => {
+					  panelSet.show('panel-2', true, { trigger: button });
+					});
+				//-
+
+
+			.example.api
+				h3.code open(transition?: boolean): void
+
+				p Opens a closable panelset (only works if #[code closable: true]).
+
+				h4 Parameter:
+				dl
+					dt.code transition (optional)
+					dd Whether to animate the opening. Default: #[code true]
+
+				br
+				+codeblock('JavaScript').
+					// Open with animation
+					panelSet.open();
+					
+					// Open instantly
+					panelSet.open(false);
+				//-
+
+
+			.example.api
+				h3.code close(transition?: boolean): void
+
+				p Closes a closable panelset (only works if #[code closable: true]).
+
+				h4 Parameter:
+				dl
+					dt.code transition (optional)
+					dd Whether to animate the closing. Default: #[code true]
+
+				br
+				+codeblock('JavaScript').
+					// Close with animation
+					panelSet.close();
+					
+					// Close instantly
+					panelSet.close(false);
+				//-
+
+
+			.example.api
+				h3.code toggle(transition?: boolean): void
+
+				p Toggles a closable panelset between open and closed (only works if #[code closable: true]).
+
+				h4 Parameter:
+				dl
+					dt.code transition (optional)
+					dd Whether to animate the toggle. Default: #[code true]
+
+				br
+				+codeblock('JavaScript').
+					// Toggle with animation
+					panelSet.toggle();
+					
+					// Toggle instantly
+					panelSet.toggle(false);
+				//-
+
+
+			.example.api
+				h3.code getActive(): string | null
+
+				p Returns the ID of the currently active panel.
+
+				h4 Returns:
+				p Panel ID string, or #[code null] if no panel is active
+
+				br
+				+codeblock('JavaScript').
+					const activePanelId = panelSet.getActive();
+					console.log('Current panel:', activePanelId);
+					
+					if (panelSet.getActive() === 'panel-3') {
+					  // Do something when panel 3 is active
+					}
+				//-
+
+
+
+			.example.api
+				h3.code onBeforeActivate(handler: Function, options?: { once: boolean }): void
+
+				p Registers a handler for async content loading before panel activation.
+
+
+				h4 Parameters:
+				dl
+					dt.code handler
+					dd Function #[code (targetPanel: HTMLElement, signal: AbortSignal) => Promise | void]
+					
+					dt.code options (optional)
+					dd Object with optional #[code once] property to register a one-time handler. If set to #[code true], the content loads only once and is cached. Otherwise, it reloads every time.
+		
+
+				p The handler receives the target panel element and an AbortSignal for cancellation. Return a promise to delay activation until loading completes. 
+
+				br
+				+codeblock('JavaScript').
+					// Always reload (default)
+					panelSet.onBeforeActivate((targetPanel, signal) => {
+					return fetch(`/api/panel/${targetPanel.id}`, { signal })
+					  .then(res => res.text())
+					  .then(html => targetPanel.innerHTML = html);
+					});
+
+					// Load once, cache forever
+					panelSet.onBeforeActivate((targetPanel, signal) => {
+					return fetch(`/api/panel/${targetPanel.id}`, { signal })
+					  .then(res => res.text())
+					  .then(html => targetPanel.innerHTML = html);
+					}, { once: true });
+				//-
+
+
+
+
+
+
+
+
+	.lane
+		.container
+			h2 Instance properties
+
+			.example.api
+				h3.code element: HTMLElement
+
+				p #[strong Read-only.] Reference to the PanelSet DOM element.
+
+				+codeblock('JS').
+					console.log(panelSet.element.id);
+					panelSet.element.classList.add('custom-class');
+				//-
+			.example.api
+				h3.code config: PanelSetConfig
+
+				p #[strong Read-only.] The merged configuration object.
+
+				+codeblock('JS').
+					console.log(panelSet.config.transitions);
+					console.log(panelSet.config.closable);
+				//-
+
+
+
+
+
+
+
+
+
+	.lane
+		.container
+			h2 Static methods
+
+			.example.api
+				h3.code PanelSet.init(selector?: string, options?: PanelSetConfig): PanelSet[]
+
+				p Auto-initializes all panelsets matching the selector.
+
+				h4 Parameters:
+				dl
+					dt.code selector (optional)
+					dd CSS selector for elements to initialize. Default: <code>'[data-panelset]'</code>
+					
+					dt.code options (optional)
+					dd Configuration object applied to all instances
+
+				h4 Returns:
+				p Array of created PanelSet instances
+				p Note: Stores instance reference on container as #[code container.panelSet]
+
+				br
+				+codeblock('JavaScript').
+					// Initialize all [data-panelset] elements
+					const instances = PanelSet.init();
+					
+					// Initialize specific elements
+					const instances = PanelSet.init('.my-panelsets');
+					
+					// With global options
+					const instances = PanelSet.init('[data-panelset]', {
+					  transitions: true,
+					  debug: false
+					});
+					
+					// Access via container
+					const container = document.getElementById('my-panelset');
+					container.panelSet.setActive('panel-2');
+				//-
+
+			.example.api
+				h3.code PanelSet.init(options: PanelSetConfig): PanelSet[]
+
+				p Alternative signature: Pass only options, uses default selector.
+
+				h4 Parameters:
+				dl
+					dt.code options (optional)
+					dd Configuration object applied to all instances
+
+				br
+				+codeblock('JavaScript').
+					const instances = PanelSet.init({
+					  transitions: false,
+					  debug: true
+					});
+				//-
+
+
+
+
+	.lane
+		.container
+			h2 Events
+			p All events are CustomEvents dispatched from the container element with a #[code detail] object. See the #[a(href="events.html") Events] page for detailed documentation.
+
+
+			.example.white
+				table(style="width: 100%; border-collapse: collapse; margin: 0;")
+					thead
+						tr
+							th(style="text-align: left; padding: 0.5rem; border-bottom: 2px solid #e5e7eb;") Event Name
+							th(style="text-align: left; padding: 0.5rem; border-bottom: 2px solid #e5e7eb;") When Fired
+							th(style="text-align: left; padding: 0.5rem; border-bottom: 2px solid #e5e7eb;") Detail Properties
+					tbody
+						tr
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code ps:ready]
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") When instance is initialized
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code element]
+
+						tr
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code ps:beforeactivate]
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") Before activation begins (for async loading)
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code panelId, targetPanel, outgoingPanel, signal, promise]
+
+						tr
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code ps:activationstart]
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") When panel activation begins
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code panelId, trigger]
+						tr
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code ps:activationcomplete]
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") When activation finishes
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code panelId, trigger]
+						tr
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code ps:activationaborted]
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") When activation is interrupted
+							td(style="padding: 0.5rem; border-bottom: 1px solid #e5e7eb;") #[code panelId, trigger]
+	.lane
+		.container
+			h2 TypeScript types
+			p PanelSet is fully typed. Import types alongside the class:
+
+
+			+codeblock('JS').
+				import { 
+				PanelSet, 
+				  type PanelSetConfig,
+				  type ActivationStartDetail,
+				  type ActivationCompleteDetail,
+				  type ActivationAbortedDetail,
+				  type ActivationOptions,
+				  type DebugConfig
+				} from 'panelset/lite';
+				
+				// Type-safe configuration
+				const config: PanelSetConfig = {
+				  transitions: { height: true, panels: false },
+				  closable: true,
+				  debug: 'verbose'
+				};
+				
+				const panelSet = new PanelSet('#my-panelset', config);
+				
+				// Type-safe event handling
+				container.addEventListener('ps:activationstart', (e) => {
+				  const event = e as CustomEvent<ActivationStartDetail>;
+				  console.log(event.detail.panelId);
+				});
+
+	.lane
+		.container
+			h2 Complete example
+
+
+			+codeblock('JS').
+				import { PanelSet } from 'panelset/lite';
+				import 'panelset/lib/panelset-lite.css';
+				
+				// Initialize with options
+				const panelSet = new PanelSet('#my-tabs', {
+				  transitions: true,
+				  closable: false,
+				  debug: false
+				});
+				
+				// Event listeners
+				panelSet.container.addEventListener('ps:activationstart', (e) => {
+				  console.log('Starting:', e.detail.panelId);
+				});
+				
+				panelSet.container.addEventListener('ps:activationcomplete', (e) => {
+				  console.log('Complete:', e.detail.panelId);
+				
+				  // Focus management
+				  const panel = document.getElementById(e.detail.panelId);
+				  panel?.querySelector('input, button')?.focus();
+				});
+				
+				// Programmatic control
+				document.getElementById('next-btn').addEventListener('click', async () => {
+				  const current = panelSet.getActive();
+				  if (current === 'step-1') {
+				    panelSet.setActive('step-2');
+				  } else if (current === 'step-2') {
+				    panelSet.setActive('step-3');
+				  }
+				});
+				
+				// Or use init for auto-initialization
+				const instances = PanelSet.init('[data-panelset]', {
+				  transitions: true
+				});
+
+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/configuration.pug

@@ -0,0 +1,173 @@
+extends /docs/views/templates/layouts/_base
+
+append variables
+	- pagetitle = "Configuration"
+
+
+block content
+	.lane
+		.container
+			.page-header
+				h1 Configuration
+				p.lead Configure PanelSet behavior via constructor options or data attributes
+
+	.lane
+		.container
+			h2 Setting the options
+			.title-text
+				h3 Through JavaScript options
+				p You can configure PanelSet when initializing it by passing an options object.
+
+			+codeblock('JS').
+				// Set the options to all PanelSets:
+				PanelSet.init({
+				    transitions: true,
+				    closable: false,
+				    emptyPanelHeight: 200,
+				    debug: false
+				});
+
+				// Set the options to a specific PanelSet:
+				PanelSet.init('#my-panelset', {
+				    transitions: true,
+				    closable: false,
+				    emptyPanelHeight: 200,
+				    debug: false
+				});
+
+				// Or create a named instance directly for later reference:
+				const myPanelSet = new PanelSet('#my-panelset', {
+				    transitions: true,
+				    closable: false,
+				    emptyPanelHeight: 200,
+				    debug: false
+				});
+
+
+		.container
+			.title-text
+				h3 Through data-attributes
+				p Or configure via HTML data-attributes on the panelset container:
+					
+				
+			+codeblock('HTML')
+				#my-panelset(data-panelset data-transitions="true" data-closable data-empty-panel-height="300" data-debug="verbose")
+					// Panels go here
+				//-
+
+	.lane
+		.container
+			h2 Available options
+			
+			.example.api
+				h3.code.method-signature transitions: boolean | { height: boolean, panels: boolean }
+				p Used for setting transitions on or off.
+				h4 Default: #[code true]
+				
+				h4 Usage examples:
+
+				.card-row
+					.card
+						h4 JavaScript options
+						ul
+							li #[code {transitions: true}] - Enable all transitions
+							li #[code {transitions: false}] - Disable all transitions
+							li #[code {transitions: {height: false}}] - Disable height transitions only
+					.card
+						h4 Data attributes
+						ul
+							li #[code data-transitions="false"] - Disable all transitions
+							li #[code data-transitions='{"height":false}'] - Disable height transitions only
+
+
+
+			.example.api
+				h3.code.method-signature closable: boolean
+				p When enabled, panelsets can be closed (height: 0) and reopened.
+				h4 Default: #[code false]
+				
+				h4 Usage examples:
+
+				.card-row
+					.card
+						h4 JavaScript options
+						ul
+							li #[code {closable: true}] - Enable closable panelset
+							li #[code {closable: false}] - Disable closable panelset
+
+					.card
+						h4 Data attributes
+						ul
+							li #[code data-closable] - Enable closable panelset
+
+			.example.api
+				h3.code.method-signature emptyPanelHeight: number
+				p Placeholder height in pixels when no panel is active. This is used if there is a delay in loading the panel content, and there is no previous panel to show the spinner on.
+				h4 Default: #[code 200]
+				
+				h4 Usage examples:
+
+				.card-row
+					.card
+						h4 JavaScript options
+						ul
+							li #[code {emptyPanelHeight: 200}] - Set placeholder height to 200 pixels
+							li #[code {emptyPanelHeight: 300}] - Set placeholder height to 300 pixels
+
+					.card
+						h4 Data attributes
+						ul
+							li #[code data-empty-panel-height="300"] - Set placeholder height to 300 pixels
+
+
+			.example.api
+				h3.code.method-signature loadingDelay: number
+				p Delay in milliseconds before showing the loading spinner. Prevents spinner flash on fast connections.
+				h4 Default: #[code 300]
+				
+				h4 Usage examples:
+
+				.card-row
+					.card
+						h4 JavaScript options
+						ul
+							li #[code {loadingDelay: 200}] - Set loading delay to 200 milliseconds
+							li #[code {loadingDelay: 300}] - Set loading delay to 300 milliseconds
+
+					.card
+						h4 Data attributes
+						ul
+							li #[code data-loading-delay="300"] - Set loading delay to 300 milliseconds
+
+			.example.api
+				h3.code.method-signature debug: boolean
+				p Used for logging and debugging purposes.
+				h4 Default: #[code false]
+				
+				h4 Usage examples:
+
+				.card-row
+					.card
+						h4 JavaScript options
+						ul
+							li #[code {debug: true}] - Enable debugging
+							li #[code {debug: false}] - Disable debugging
+					.card
+						h4 Data attributes
+						ul
+							li #[code data-debug] - Enable debugging
+
+
+
+
+
+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});