@dodlhuat/basix 1.3.2 → 1.3.4

package/js/modal.js

@@ -1,8 +1,15 @@
 import { sanitizeHtml } from './utils.js';
 const CLOSE_ICON = '<div class="icon icon-close close"></div>';
+/** Overlay dialog with optional header, footer, close button, and type variants. */
 class Modal {
+    content;
+    header;
+    footer;
+    closeable;
+    type;
+    template;
+    modalWrapper = null;
     constructor(contentOrOptions, header, footer, closeable = true, type = 'default') {
-        this.modalWrapper = null;
         if (typeof contentOrOptions === 'object') {
             this.content = contentOrOptions.content;
             this.header = contentOrOptions.header;
@@ -18,9 +25,6 @@ class Modal {
             this.type = type;
         }
         this.template = this.buildTemplate();
-        this.hide = this.hide.bind(this);
-        this.handleEscape = this.handleEscape.bind(this);
-        this.handleBackgroundClick = this.handleBackgroundClick.bind(this);
     }
     show() {
         this.hide();
@@ -45,11 +49,10 @@ class Modal {
             wrapper.classList.add('is-visible');
         });
     }
-    hide() {
+    hide = () => {
         const wrapper = this.modalWrapper;
         if (!wrapper)
             return;
-        // Remove event listeners
         const closeBtn = wrapper.querySelector('.close');
         closeBtn?.removeEventListener('click', this.hide);
         const background = wrapper.querySelector('.modal-background');
@@ -63,19 +66,19 @@ class Modal {
                 this.modalWrapper = null;
             }
         }, 300);
-    }
-    handleEscape(e) {
+    };
+    handleEscape = (e) => {
         if (e.key === 'Escape') {
             this.hide();
         }
-    }
-    handleBackgroundClick(e) {
+    };
+    handleBackgroundClick = (e) => {
         if (e.target?.classList.contains('modal-background')) {
             this.hide();
         }
-    }
+    };
     buildTemplate() {
-        const parts = ['<div class="modal">'];
+        const parts = [`<div class="modal modal-${this.type}">`];
         if (this.closeable) {
             parts.push(CLOSE_ICON);
         }

package/js/popover.d.ts

@@ -2,6 +2,7 @@ import type { Placement } from './position.js';
 type PopoverPlacement = Placement | 'auto';
 type PopoverAlign = 'start' | 'center' | 'end';
 type PopoverTrigger = 'click' | 'hover';
+/** Configuration options for a Popover instance. */
 interface PopoverOptions {
     content: string;
     placement?: PopoverPlacement;
@@ -15,6 +16,7 @@ interface PopoverOptions {
     onOpen?: () => void;
     onClose?: () => void;
 }
+/** Anchored popover triggered by click or hover, with auto-placement and optional arrow. */
 declare class Popover {
     private static openPopovers;
     private static idCounter;

package/js/popover.js

@@ -1,31 +1,16 @@
 import { computePosition } from './position.js';
 import { sanitizeHtml } from './utils.js';
-// Must match $arrow in popover.scss
 const ARROW_SIZE = 6;
+/** Anchored popover triggered by click or hover, with auto-placement and optional arrow. */
 class Popover {
+    static openPopovers = new Set();
+    static idCounter = 0;
+    trigger;
+    opts;
+    popoverEl = null;
+    _isOpen = false;
+    hoverTimer = null;
     constructor(triggerEl, options) {
-        this.popoverEl = null;
-        this._isOpen = false;
-        this.hoverTimer = null;
-        // ── Event handlers ─────────────────────────────────────────────────────────
-        this.onClick = () => { this.toggle(); };
-        this.onMouseEnter = () => {
-            if (this.hoverTimer !== null)
-                clearTimeout(this.hoverTimer);
-            this.open();
-        };
-        this.onMouseLeave = () => {
-            this.hoverTimer = window.setTimeout(() => this.close(), 120);
-        };
-        this.onOutsideClick = (e) => {
-            const t = e.target;
-            if (!this.popoverEl?.contains(t) && !this.trigger.contains(t))
-                this.close();
-        };
-        this.onEscape = (e) => {
-            if (e.key === 'Escape')
-                this.close();
-        };
         const el = typeof triggerEl === 'string'
             ? document.querySelector(triggerEl)
             : triggerEl;
@@ -47,7 +32,6 @@ class Popover {
         };
         this.attachTrigger();
     }
-    // ── Public API ─────────────────────────────────────────────────────────────
     get isOpen() { return this._isOpen; }
     open() {
         if (this._isOpen)
@@ -109,7 +93,6 @@ class Popover {
             });
         });
     }
-    // ── Build ──────────────────────────────────────────────────────────────────
     buildEl() {
         const id = `popover-${++Popover.idCounter}`;
         const el = document.createElement('div');
@@ -117,8 +100,6 @@ class Popover {
         el.id = id;
         el.setAttribute('role', 'dialog');
         el.setAttribute('data-arrow', String(this.opts.arrow));
-        // Wrap plain content in .popover-body so it gets proper padding.
-        // Skip wrapping when content already uses structured popover elements.
         const hasStructure = /class="popover-(header|body|footer|menu)/.test(this.opts.content);
         const safeContent = sanitizeHtml(this.opts.content);
         el.innerHTML = hasStructure
@@ -128,7 +109,6 @@ class Popover {
         this.trigger.setAttribute('aria-controls', id);
         return el;
     }
-    // ── Positioning ────────────────────────────────────────────────────────────
     reposition() {
         if (!this.popoverEl)
             return;
@@ -145,6 +125,24 @@ class Popover {
         this.popoverEl.style.left = `${left}px`;
         this.popoverEl.style.top = `${top}px`;
     }
+    onClick = () => { this.toggle(); };
+    onMouseEnter = () => {
+        if (this.hoverTimer !== null)
+            clearTimeout(this.hoverTimer);
+        this.open();
+    };
+    onMouseLeave = () => {
+        this.hoverTimer = window.setTimeout(() => this.close(), 120);
+    };
+    onOutsideClick = (e) => {
+        const t = e.target;
+        if (!this.popoverEl?.contains(t) && !this.trigger.contains(t))
+            this.close();
+    };
+    onEscape = (e) => {
+        if (e.key === 'Escape')
+            this.close();
+    };
     attachTrigger() {
         if (this.opts.triggerMode === 'click') {
             this.trigger.addEventListener('click', this.onClick);
@@ -160,6 +158,4 @@ class Popover {
         this.trigger.removeEventListener('mouseleave', this.onMouseLeave);
     }
 }
-Popover.openPopovers = new Set();
-Popover.idCounter = 0;
 export { Popover };

package/js/position.d.ts

@@ -4,6 +4,7 @@
  */
 type Placement = 'top' | 'bottom' | 'left' | 'right';
 type Align = 'start' | 'center' | 'end';
+/** Options accepted by `computePosition`. */
 interface PositionOptions {
     placement: Placement | 'auto';
     align?: Align;
@@ -11,6 +12,7 @@ interface PositionOptions {
     margin?: number;
     arrowSize?: number;
 }
+/** Result returned by `computePosition`. */
 interface PositionResult {
     left: number;
     top: number;

package/js/position.js

@@ -44,7 +44,6 @@ function computePosition(trigger, floating, opts) {
     const placement = opts.placement === 'auto'
         ? bestPlacement(trigger, floating, offset)
         : maybeFlip(opts.placement, trigger, floating, offset);
-    // Main-axis offset
     let left = 0, top = 0;
     switch (placement) {
         case 'top':
@@ -60,7 +59,6 @@ function computePosition(trigger, floating, opts) {
             left = trigger.right + offset;
             break;
     }
-    // Cross-axis alignment
     if (placement === 'top' || placement === 'bottom') {
         switch (align) {
             case 'start':
@@ -87,13 +85,11 @@ function computePosition(trigger, floating, opts) {
                 break;
         }
     }
-    // Clamp to viewport
     const l = Math.max(margin, Math.min(window.innerWidth - floating.width - margin, left));
     const t = Math.max(margin, Math.min(window.innerHeight - floating.height - margin, top));
-    // Arrow offset: keep arrow centred on the trigger even after viewport clamping
     let arrowOffset;
     if (opts.arrowSize !== undefined) {
-        const minOff = opts.arrowSize + 8; // min distance from rounded corner
+        const minOff = opts.arrowSize + 8;
         if (placement === 'top' || placement === 'bottom') {
             const raw = trigger.left + trigger.width / 2 - l;
             arrowOffset = Math.max(minOff, Math.min(floating.width - minOff, raw));

package/js/push-menu.d.ts

@@ -1,3 +1,4 @@
+/** DOM element references managed by the PushMenu static class. */
 interface PushMenuElements {
     navigation: HTMLElement | null;
     content: HTMLElement | null;
@@ -6,6 +7,7 @@ interface PushMenuElements {
     controlIcon: HTMLElement | null;
     backdrop: HTMLElement | null;
 }
+/** Static class that manages a push-style side navigation panel. */
 declare class PushMenu {
     private static elements;
     private static initialized;

package/js/push-menu.js

@@ -1,4 +1,16 @@
+/** Static class that manages a push-style side navigation panel. */
 class PushMenu {
+    static elements = {
+        navigation: null,
+        content: null,
+        menu: null,
+        header: null,
+        controlIcon: null,
+        backdrop: null
+    };
+    static initialized = false;
+    static panelStack = [];
+    static boundHandleNavigationChange;
     static init() {
         if (this.initialized) {
             console.warn('PushMenu: Already initialized');
@@ -14,7 +26,6 @@ class PushMenu {
         this.elements.backdrop?.addEventListener('click', this.handleBackdropClick);
         this.initialized = true;
     }
-    // ─── Panel construction ────────────────────────────────────────────────
     static buildPanels() {
         const menu = this.elements.menu;
         if (!menu)
@@ -22,18 +33,15 @@ class PushMenu {
         const rootUl = menu.querySelector(':scope > ul');
         if (!rootUl)
             return;
-        // Wrap root ul in a panel
         const rootPanel = document.createElement('div');
         rootPanel.classList.add('push-menu-panel', 'is-active');
         rootPanel.dataset.level = '0';
         rootPanel.appendChild(rootUl);
         menu.appendChild(rootPanel);
-        // Recursively extract nested uls into sibling panels
         this.extractSubPanels(rootPanel, 1);
         this.panelStack = [rootPanel];
     }
     static extractSubPanels(panel, level) {
-        // Collect all uls currently in this panel before any mutations
         const uls = Array.from(panel.querySelectorAll('ul'));
         for (const ul of uls) {
             const listItems = Array.from(ul.children);
@@ -41,14 +49,11 @@ class PushMenu {
                 const childUl = li.querySelector(':scope > ul');
                 if (!childUl)
                     continue;
-                // Determine label from the immediate anchor child
                 const parentAnchor = li.querySelector(':scope > a');
                 const title = parentAnchor?.textContent?.trim() ?? '';
-                // ── Build sub-panel ──────────────────────────────────────
                 const subPanel = document.createElement('div');
                 subPanel.classList.add('push-menu-panel');
                 subPanel.dataset.level = String(level);
-                // Header: back button + breadcrumb title
                 const header = document.createElement('div');
                 header.classList.add('push-menu-panel-header');
                 const backBtn = document.createElement('button');
@@ -62,15 +67,11 @@ class PushMenu {
                 header.appendChild(backBtn);
                 header.appendChild(titleEl);
                 subPanel.appendChild(header);
-                // Move the child ul into the sub-panel
                 subPanel.appendChild(childUl);
-                // Append sub-panel as sibling inside the nav
                 this.elements.menu?.appendChild(subPanel);
-                // ── Replace anchor with a trigger span in the parent li ──
                 const trigger = document.createElement('span');
                 trigger.classList.add('push-menu-item');
                 trigger.textContent = title;
-                // Chevron icon
                 const chevron = document.createElement('span');
                 chevron.classList.add('push-menu-chevron');
                 chevron.setAttribute('aria-hidden', 'true');
@@ -83,12 +84,10 @@ class PushMenu {
                     li.prepend(trigger);
                 }
                 trigger.addEventListener('click', () => PushMenu.openPanel(subPanel));
-                // Recurse into the newly created sub-panel
                 this.extractSubPanels(subPanel, level + 1);
             }
         }
     }
-    // ─── Panel navigation ──────────────────────────────────────────────────
     static openPanel(panel) {
         const currentPanel = this.panelStack[this.panelStack.length - 1];
         currentPanel.classList.remove('is-active');
@@ -109,7 +108,6 @@ class PushMenu {
         const menu = this.elements.menu;
         if (!menu)
             return;
-        // Wait for the close animation before snapping panels back
         setTimeout(() => {
             const panels = Array.from(menu.querySelectorAll('.push-menu-panel'));
             panels.forEach((panel, index) => {
@@ -122,7 +120,6 @@ class PushMenu {
             }
         }, 300);
     }
-    // ─── Open / close ──────────────────────────────────────────────────────
     static handleNavigationChange() {
         const isPushed = this.elements.content?.classList.contains('pushed') ?? false;
         if (!isPushed) {
@@ -154,6 +151,16 @@ class PushMenu {
             }
         }
     }
+    static clickNav = () => {
+        const navigation = PushMenu.elements.navigation;
+        navigation?.click();
+    };
+    static handleBackdropClick = () => {
+        if (PushMenu.isOpen()) {
+            const navigation = PushMenu.elements.navigation;
+            navigation?.click();
+        }
+    };
     static open() {
         if (!this.elements.content?.classList.contains('pushed')) {
             this.pushToggle();
@@ -194,24 +201,4 @@ class PushMenu {
         this.elements.backdrop = document.querySelector('.push-menu-backdrop');
     }
 }
-PushMenu.elements = {
-    navigation: null,
-    content: null,
-    menu: null,
-    header: null,
-    controlIcon: null,
-    backdrop: null
-};
-PushMenu.initialized = false;
-PushMenu.panelStack = [];
-PushMenu.clickNav = () => {
-    const navigation = PushMenu.elements.navigation;
-    navigation?.click();
-};
-PushMenu.handleBackdropClick = () => {
-    if (PushMenu.isOpen()) {
-        const navigation = PushMenu.elements.navigation;
-        navigation?.click();
-    }
-};
 export { PushMenu };

package/js/range-slider.d.ts

@@ -1,3 +1,4 @@
+/** Enhances a native range input with a CSS fill-percentage custom property. */
 declare class RangeSlider {
     private readonly input;
     constructor(input: HTMLInputElement);

package/js/range-slider.js

@@ -1,8 +1,7 @@
+/** Enhances a native range input with a CSS fill-percentage custom property. */
 class RangeSlider {
+    input;
     constructor(input) {
-        this.handleInput = () => {
-            this.update();
-        };
         this.input = input;
         this.update();
         this.input.addEventListener('input', this.handleInput);
@@ -18,6 +17,9 @@ class RangeSlider {
         const pct = ((+this.input.value - min) / (max - min)) * 100;
         this.input.style.setProperty('--range-fill', `${pct}%`);
     }
+    handleInput = () => {
+        this.update();
+    };
     destroy() {
         this.input.removeEventListener('input', this.handleInput);
         this.input.style.removeProperty('--range-fill');

package/js/scroll.d.ts

@@ -1,8 +1,10 @@
+/** Options for the Scroll.to() utility. */
 interface ScrollOptions {
     behavior?: ScrollBehavior;
     offset?: number;
     block?: ScrollLogicalPosition;
 }
+/** Static utility for smooth-scrolling to a target element with header offset support. */
 declare class Scroll {
     static to(target: string | Element, options?: ScrollOptions): void;
 }

package/js/scroll.js

@@ -1,3 +1,4 @@
+/** Static utility for smooth-scrolling to a target element with header offset support. */
 class Scroll {
     static to(target, options = {}) {
         const fixed_header = document.querySelector('.main-header');

package/js/scrollbar.d.ts

@@ -1,9 +1,11 @@
+/** DOM element references for a Scrollbar instance. */
 interface ScrollbarElements {
     viewport: HTMLElement;
     content: HTMLElement;
     track: HTMLElement;
     thumb: HTMLElement;
 }
+/** Custom scrollbar overlay that replaces the native scrollbar with a draggable thumb. */
 declare class Scrollbar {
     private static readonly instances;
     private static activeInstance;

package/js/scrollbar.js

@@ -1,19 +1,36 @@
+/** Custom scrollbar overlay that replaces the native scrollbar with a draggable thumb. */
 class Scrollbar {
+    static instances = new WeakMap();
+    static activeInstance = null;
+    static globalListenersInstalled = false;
+    static instanceCount = 0;
+    static globalListenerAbortController = null;
+    container;
+    viewport;
+    content;
+    track;
+    thumb;
+    MIN_THUMB_HEIGHT;
+    ro;
+    dragging = false;
+    activePointerId = null;
+    startPointerY = 0;
+    startThumbTop = 0;
+    boundPointerMove;
+    boundPointerUp;
+    boundThumbPointerDown;
+    boundTrackClick;
+    boundViewportScroll;
+    boundUpdateThumb;
+    boundContainerWheel;
     constructor(container) {
-        this.dragging = false;
-        this.activePointerId = null;
-        this.startPointerY = 0;
-        this.startThumbTop = 0;
         this.container = container;
-        // Query and validate required elements
         const elements = this.getRequiredElements(container);
         this.viewport = elements.viewport;
         this.content = elements.content;
         this.track = elements.track;
         this.thumb = elements.thumb;
-        // Get minimum thumb height from CSS variable or use default
         this.MIN_THUMB_HEIGHT = this.getMinThumbHeight();
-        // Bind all event handlers once
         this.boundPointerMove = this.handlePointerMove.bind(this);
         this.boundPointerUp = this.handlePointerUp.bind(this);
         this.boundThumbPointerDown = this.handleThumbPointerDown.bind(this);
@@ -21,17 +38,13 @@ class Scrollbar {
         this.boundViewportScroll = this.updateThumb.bind(this);
         this.boundUpdateThumb = this.updateThumb.bind(this);
         this.boundContainerWheel = this.handleContainerWheel.bind(this);
-        // Setup ResizeObserver
         this.ro = new ResizeObserver(this.boundUpdateThumb);
-        // Initialize
         this.attachEventListeners();
         Scrollbar.instances.set(container, this);
-        // Track instances and install global listeners once for all
         Scrollbar.instanceCount++;
         if (!Scrollbar.globalListenersInstalled) {
             Scrollbar.installGlobalListeners();
         }
-        // Initial thumb update
         requestAnimationFrame(this.boundUpdateThumb);
     }
     getRequiredElements(container) {
@@ -68,12 +81,10 @@ class Scrollbar {
         Scrollbar.globalListenersInstalled = true;
     }
     attachEventListeners() {
-        // Instance-specific events
         this.viewport.addEventListener('scroll', this.boundViewportScroll, { passive: true });
         this.thumb.addEventListener('pointerdown', this.boundThumbPointerDown);
         this.track.addEventListener('click', this.boundTrackClick);
         this.container.addEventListener('wheel', this.boundContainerWheel, { passive: false });
-        // Observe size changes
         this.ro.observe(this.viewport);
         this.ro.observe(this.content);
         window.addEventListener('resize', this.boundUpdateThumb);
@@ -82,17 +93,14 @@ class Scrollbar {
         const viewportHeight = this.viewport.clientHeight;
         const contentHeight = this.content.scrollHeight;
         const trackHeight = this.track.clientHeight;
-        // Hide thumb if content fits in viewport
         if (contentHeight <= viewportHeight + 1) {
             this.thumb.style.display = 'none';
             return;
         }
         this.thumb.style.display = '';
-        // Calculate thumb size
         const ratio = viewportHeight / contentHeight;
         const thumbHeight = Math.max(Math.floor(ratio * trackHeight), this.MIN_THUMB_HEIGHT);
         this.thumb.style.height = `${thumbHeight}px`;
-        // Calculate thumb position
         const maxScroll = contentHeight - viewportHeight;
         const maxThumbTop = trackHeight - thumbHeight;
         const scrollRatio = this.viewport.scrollTop / (maxScroll || 1);
@@ -104,7 +112,6 @@ class Scrollbar {
         this.dragging = true;
         this.activePointerId = e.pointerId;
         Scrollbar.activeInstance = this;
-        // Capture pointer for reliable tracking
         try {
             this.thumb.setPointerCapture(e.pointerId);
         }
@@ -115,11 +122,9 @@ class Scrollbar {
         const thumbRect = this.thumb.getBoundingClientRect();
         const trackRect = this.track.getBoundingClientRect();
         this.startThumbTop = thumbRect.top - trackRect.top;
-        // Prevent text selection during drag
         document.body.style.userSelect = 'none';
     }
     handlePointerMove(e) {
-        // Only handle events for the active pointer
         if (!this.dragging || this.activePointerId !== e.pointerId) {
             return;
         }
@@ -128,10 +133,8 @@ class Scrollbar {
         const trackHeight = this.track.clientHeight;
         const thumbHeight = this.thumb.clientHeight;
         const maxThumbTop = trackHeight - thumbHeight;
-        // Calculate new thumb position
         const newThumbTop = Math.max(0, Math.min(maxThumbTop, this.startThumbTop + pointerDelta));
         this.thumb.style.top = `${newThumbTop}px`;
-        // Update viewport scroll position
         const contentHeight = this.content.scrollHeight;
         const viewportHeight = this.viewport.clientHeight;
         const maxScroll = contentHeight - viewportHeight;
@@ -143,7 +146,6 @@ class Scrollbar {
             return;
         }
         this.dragging = false;
-        // Release pointer capture
         try {
             this.thumb.releasePointerCapture(e.pointerId);
         }
@@ -155,7 +157,6 @@ class Scrollbar {
         document.body.style.userSelect = '';
     }
     handleTrackClick(e) {
-        // Ignore clicks directly on the thumb
         if (e.target === this.thumb) {
             return;
         }
@@ -163,11 +164,9 @@ class Scrollbar {
         const clickY = e.clientY - trackRect.top;
         const thumbHeight = this.thumb.clientHeight;
         const trackHeight = this.track.clientHeight;
-        // Center thumb on click position
         const targetThumbTop = clickY - thumbHeight / 2;
         const maxThumbTop = trackHeight - thumbHeight;
         const clampedThumbTop = Math.max(0, Math.min(maxThumbTop, targetThumbTop));
-        // Calculate corresponding scroll position
         const contentHeight = this.content.scrollHeight;
         const viewportHeight = this.viewport.clientHeight;
         const maxScroll = contentHeight - viewportHeight;
@@ -186,21 +185,16 @@ class Scrollbar {
         this.viewport.scrollTop += e.deltaY;
     }
     destroy() {
-        // Remove event listeners
         this.viewport.removeEventListener('scroll', this.boundViewportScroll);
         this.thumb.removeEventListener('pointerdown', this.boundThumbPointerDown);
         this.track.removeEventListener('click', this.boundTrackClick);
         this.container.removeEventListener('wheel', this.boundContainerWheel);
         window.removeEventListener('resize', this.boundUpdateThumb);
-        // Disconnect observer
         this.ro.disconnect();
-        // Clear from instances map
         Scrollbar.instances.delete(this.container);
-        // Clear active instance if this was it
         if (Scrollbar.activeInstance === this) {
             Scrollbar.activeInstance = null;
         }
-        // Uninstall global listeners when last instance is destroyed
         Scrollbar.instanceCount--;
         if (Scrollbar.instanceCount === 0) {
             Scrollbar.globalListenerAbortController?.abort();
@@ -208,7 +202,6 @@ class Scrollbar {
             Scrollbar.globalListenersInstalled = false;
         }
     }
-    // Static factory methods
     static create(elementOrSelector) {
         const container = typeof elementOrSelector === 'string'
             ? document.querySelector(elementOrSelector)
@@ -232,9 +225,4 @@ class Scrollbar {
         return Scrollbar.instances.get(container);
     }
 }
-Scrollbar.instances = new WeakMap();
-Scrollbar.activeInstance = null;
-Scrollbar.globalListenersInstalled = false;
-Scrollbar.instanceCount = 0;
-Scrollbar.globalListenerAbortController = null;
 export { Scrollbar };

package/js/select.d.ts

@@ -1,3 +1,4 @@
+/** Enhances a native `<select>` element with a custom styled dropdown. */
 declare class Select {
     private readonly element;
     private readonly isMultiselect;