@dodlhuat/basix 1.3.2 → 1.3.4

package/js/chart.js

@@ -7,13 +7,16 @@ const FALLBACK_COLORS = [
     '#8B5CF6', '#06B6D4', '#F97316', '#EC4899',
 ];
 const SVG_NS = 'http://www.w3.org/2000/svg';
-// ─── Chart ──────────────────────────────────────────────────────────────────
+/** SVG-based chart component supporting line, area, column, bar, and pie types. */
 class Chart {
+    container;
+    opts;
+    tooltip;
+    colors = [];
+    abortController = new AbortController();
+    resizeTimer = null;
+    resizeObserver = null;
     constructor(selector, options) {
-        this.colors = [];
-        this.abortController = new AbortController();
-        this.resizeTimer = null;
-        this.resizeObserver = null;
         const el = typeof selector === 'string'
             ? document.querySelector(selector)
             : selector;
@@ -37,7 +40,6 @@ class Chart {
         this.render();
         this.attachResizeObserver();
     }
-    // ── Render ──────────────────────────────────────────────────────────────
     render() {
         this.abortController.abort();
         this.abortController = new AbortController();
@@ -72,7 +74,6 @@ class Chart {
             this.container.appendChild(this.buildLegend());
         }
     }
-    // ── Line / Area ──────────────────────────────────────────────────────────
     renderLineOrArea(canvas, isArea) {
         const { series, height, showGrid, animate, yMin } = this.opts;
         if (!series.length || !series[0].data.length)
@@ -119,7 +120,6 @@ class Chart {
                 });
             }
             svg.appendChild(linePath);
-            // Data point markers
             s.data.forEach((d, i) => {
                 const g = this.svgEl('g', {
                     class: 'chart-point-group',
@@ -145,7 +145,6 @@ class Chart {
             });
         });
     }
-    // ── Column ───────────────────────────────────────────────────────────────
     renderColumn(canvas) {
         const { series, height, showGrid, animate, yMin } = this.opts;
         if (!series.length || !series[0].data.length)
@@ -190,7 +189,6 @@ class Chart {
             });
         });
     }
-    // ── Bar (horizontal) ─────────────────────────────────────────────────────
     renderBar(canvas) {
         const { series, height, animate } = this.opts;
         if (!series.length || !series[0].data.length)
@@ -206,7 +204,6 @@ class Chart {
         const numPts = labels.length;
         const numSeries = series.length;
         const svg = this.createSVG(canvas, svgW, svgH);
-        // Vertical grid lines
         const numTicks = 5;
         for (let t = 0; t <= numTicks; t++) {
             const x = m.left + (t / numTicks) * w;
@@ -223,7 +220,6 @@ class Chart {
             label.textContent = this.fmt(xMax * t / numTicks);
             svg.appendChild(label);
         }
-        // Category labels on Y axis
         const groupH = h / numPts;
         labels.forEach((label, i) => {
             const y = m.top + i * groupH + groupH / 2;
@@ -235,7 +231,6 @@ class Chart {
             text.textContent = label;
             svg.appendChild(text);
         });
-        // Bars
         const innerPad = groupH * 0.18;
         const barH = Math.max(2, (groupH - innerPad) / numSeries - 2);
         series.forEach((s, si) => {
@@ -259,7 +254,6 @@ class Chart {
             });
         });
     }
-    // ── Pie ──────────────────────────────────────────────────────────────────
     renderPie(canvas) {
         const { series, height, animate, showLegend } = this.opts;
         const s = series[0];
@@ -273,7 +267,7 @@ class Chart {
         const r = Math.min(svgW, svgH) / 2 - Math.max(m.top, m.left) - 8;
         const total = s.data.reduce((sum, d) => sum + d.value, 0);
         const svg = this.createSVG(canvas, svgW, svgH);
-        let startAngle = -90; // start at 12 o'clock
+        let startAngle = -90;
         s.data.forEach((d, i) => {
             const color = this.colors[i % this.colors.length];
             const sweep = (d.value / total) * 360;
@@ -290,7 +284,6 @@ class Chart {
                 const delay = i * 70;
                 path.style.animationDelay = `${delay}ms`;
             }
-            // Hover: nudge slice outward
             const { x: dx, y: dy } = this.polar(0, 0, 8, midAngle);
             path.addEventListener('mouseenter', (e) => {
                 path.style.transform = `translate(${dx}px, ${dy}px)`;
@@ -310,7 +303,6 @@ class Chart {
             this.container.appendChild(this.buildPieLegend(s, total));
         }
     }
-    // ── Axis helpers ─────────────────────────────────────────────────────────
     renderHGrid(svg, m, w, h, yMin, yMax) {
         const numTicks = 5;
         for (let i = 0; i <= numTicks; i++) {
@@ -355,7 +347,6 @@ class Chart {
             svg.appendChild(text);
         }
     }
-    // ── Geometry helpers ─────────────────────────────────────────────────────
     buildPath(pts) {
         switch (this.opts.curve) {
             case 'linear': return this.linearPath(pts);
@@ -410,7 +401,6 @@ class Chart {
         const rad = deg * Math.PI / 180;
         return { x: cx + r * Math.cos(rad), y: cy + r * Math.sin(rad) };
     }
-    // ── Legend builders ──────────────────────────────────────────────────────
     buildHeader() {
         const el = this.div('chart-header');
         if (this.opts.title) {
@@ -454,7 +444,6 @@ class Chart {
         });
         return el;
     }
-    // ── Tooltip ──────────────────────────────────────────────────────────────
     showTooltip(e, html) {
         this.tooltip.innerHTML = html;
         this.tooltip.classList.add('is-visible');
@@ -466,7 +455,6 @@ class Chart {
         const vh = window.innerHeight;
         let x = e.clientX + 14;
         let y = e.clientY - 36;
-        // Keep inside viewport
         if (x + 200 > vw)
             x = e.clientX - 14 - tt.offsetWidth;
         if (y < 0)
@@ -479,7 +467,6 @@ class Chart {
     hideTooltip() {
         this.tooltip.classList.remove('is-visible');
     }
-    // ── Event wiring ─────────────────────────────────────────────────────────
     onPoint(g, s, d, i) {
         const sig = { signal: this.abortController.signal };
         g.addEventListener('mouseenter', (e) => {
@@ -499,7 +486,6 @@ class Chart {
         rect.addEventListener('mouseleave', () => this.hideTooltip(), sig);
         rect.addEventListener('click', () => this.opts.onPointClick(s, d, i), sig);
     }
-    // ── Color resolution ─────────────────────────────────────────────────────
     resolveColors() {
         const style = getComputedStyle(this.container);
         this.colors = (this.opts.type === 'pie' ? this.opts.series[0]?.data ?? [] : this.opts.series)
@@ -507,7 +493,6 @@ class Chart {
             const css = style.getPropertyValue(`--chart-color-${i + 1}`).trim();
             return css || FALLBACK_COLORS[i % FALLBACK_COLORS.length];
         });
-        // Allow per-series color override (not pie)
         if (this.opts.type !== 'pie') {
             this.opts.series.forEach((s, i) => {
                 if (s.color)
@@ -515,7 +500,6 @@ class Chart {
             });
         }
     }
-    // ── DOM & SVG helpers ────────────────────────────────────────────────────
     div(className) {
         const el = document.createElement('div');
         el.className = className;
@@ -537,13 +521,12 @@ class Chart {
         return el;
     }
     fmt(v) {
-        if (v >= 1000000)
-            return `${(v / 1000000).toFixed(1)}M`;
-        if (v >= 1000)
-            return `${(v / 1000).toFixed(1)}K`;
+        if (v >= 1_000_000)
+            return `${(v / 1_000_000).toFixed(1)}M`;
+        if (v >= 1_000)
+            return `${(v / 1_000).toFixed(1)}K`;
         return v % 1 === 0 ? String(Math.round(v)) : v.toFixed(1);
     }
-    // ── Resize ───────────────────────────────────────────────────────────────
     attachResizeObserver() {
         this.resizeObserver = new ResizeObserver(() => {
             if (this.resizeTimer)
@@ -552,7 +535,6 @@ class Chart {
         });
         this.resizeObserver.observe(this.container);
     }
-    // ── Public API ───────────────────────────────────────────────────────────
     update(series) {
         this.opts.series = series;
         this.render();

package/js/code-viewer.d.ts

@@ -1,4 +1,5 @@
 type SupportedLanguage = 'javascript' | 'js' | 'html' | 'css';
+/** Renders syntax-highlighted code inside a container element. */
 declare class CodeViewer {
     private container;
     private code;

package/js/code-viewer.js

@@ -1,4 +1,8 @@
+/** Renders syntax-highlighted code inside a container element. */
 class CodeViewer {
+    container;
+    code;
+    language;
     constructor(elementOrSelector, code, language = 'javascript') {
         const element = typeof elementOrSelector === 'string'
             ? document.querySelector(elementOrSelector)

package/js/context-menu.d.ts

@@ -1,3 +1,4 @@
+/** Definition for a single context menu item including optional submenu. */
 interface ContextMenuItemDef {
     label: string;
     icon?: string;
@@ -10,13 +11,19 @@ interface ContextMenuItemDef {
 type ContextMenuInput = ContextMenuItemDef | 'separator' | {
     group: string;
 };
+interface ContextMenuOptions {
+    /** Path to the SVG sprite file, e.g. `'svg-icons/icons.svg'`. Required to render icons. */
+    spritePath?: string;
+}
+/** Right-click context menu with keyboard navigation and nested submenu support. */
 declare class ContextMenu {
     private items;
     private targets;
     private menuEl;
     private currentTarget;
     private abortController;
-    constructor(selectorOrElement: string | HTMLElement | HTMLElement[], items: ContextMenuInput[]);
+    private spritePath;
+    constructor(selectorOrElement: string | HTMLElement | HTMLElement[], items: ContextMenuInput[], options?: ContextMenuOptions);
     private init;
     private open;
     private close;
@@ -28,4 +35,4 @@ declare class ContextMenu {
     private activateFocused;
     destroy(): void;
 }
-export { ContextMenu, type ContextMenuInput, type ContextMenuItemDef };
+export { ContextMenu, type ContextMenuInput, type ContextMenuItemDef, type ContextMenuOptions };

package/js/context-menu.js

@@ -1,9 +1,14 @@
+/** Right-click context menu with keyboard navigation and nested submenu support. */
 class ContextMenu {
-    constructor(selectorOrElement, items) {
-        this.menuEl = null;
-        this.currentTarget = null;
-        this.abortController = new AbortController();
+    items;
+    targets;
+    menuEl = null;
+    currentTarget = null;
+    abortController = new AbortController();
+    spritePath;
+    constructor(selectorOrElement, items, options = {}) {
         this.items = items;
+        this.spritePath = options.spritePath ?? null;
         if (typeof selectorOrElement === 'string') {
             this.targets = Array.from(document.querySelectorAll(selectorOrElement));
         }
@@ -25,7 +30,6 @@ class ContextMenu {
             }, { signal });
         });
         document.addEventListener('click', () => this.close(), { signal });
-        // Close on right-click outside the menu
         document.addEventListener('contextmenu', (e) => {
             if (this.menuEl && !this.menuEl.contains(e.target)) {
                 this.close();
@@ -50,7 +54,6 @@ class ContextMenu {
                 this.activateFocused();
             }
         }, { signal });
-        // Close on scroll outside the menu
         window.addEventListener('scroll', (e) => {
             if (!this.menuEl?.contains(e.target))
                 this.close();
@@ -61,14 +64,12 @@ class ContextMenu {
         this.close();
         this.menuEl = this.buildMenu(this.items);
         document.body.appendChild(this.menuEl);
-        // Use offsetWidth/offsetHeight — unaffected by CSS transform
         const w = this.menuEl.offsetWidth;
         const h = this.menuEl.offsetHeight;
         const vw = window.innerWidth;
         const vh = window.innerHeight;
         const left = x + w > vw ? vw - w - 8 : x;
         const top = y + h > vh ? vh - h - 8 : y;
-        // Set transform-origin to match the corner the menu opens from
         const originX = x + w > vw ? 'right' : 'left';
         const originY = y + h > vh ? 'bottom' : 'top';
         this.menuEl.style.left = `${left}px`;
@@ -82,7 +83,6 @@ class ContextMenu {
         const el = this.menuEl;
         this.menuEl = null;
         el.classList.remove('is-visible');
-        // Wait for exit transition then remove from DOM
         el.addEventListener('transitionend', () => el.remove(), { once: true });
         setTimeout(() => el.isConnected && el.remove(), 200);
     }
@@ -116,11 +116,16 @@ class ContextMenu {
             li.classList.add('is-destructive');
         if (def.submenu)
             li.classList.add('has-submenu');
-        // Always render icon slot — keeps label column aligned across all items
         const iconWrap = document.createElement('span');
         iconWrap.className = 'context-menu-icon';
-        if (def.icon) {
-            iconWrap.innerHTML = `<svg class="icon-svg"><use href="svg-icons/icons.svg#${def.icon}"/></svg>`;
+        if (def.icon && this.spritePath) {
+            const svgEl = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+            svgEl.setAttribute('aria-hidden', 'true');
+            svgEl.setAttribute('fill', 'currentColor');
+            const useEl = document.createElementNS('http://www.w3.org/2000/svg', 'use');
+            useEl.setAttribute('href', `${this.spritePath}#${def.icon}`);
+            svgEl.appendChild(useEl);
+            iconWrap.appendChild(svgEl);
         }
         li.appendChild(iconWrap);
         const label = document.createElement('span');
@@ -139,7 +144,6 @@ class ContextMenu {
             li.appendChild(chevron);
             const submenuEl = this.buildMenu(def.submenu);
             li.appendChild(submenuEl);
-            // Determine flip synchronously from parent position — no rAF flash
             const shouldFlip = () => {
                 const rect = li.getBoundingClientRect();
                 return rect.right + submenuEl.offsetWidth > window.innerWidth;
@@ -179,7 +183,6 @@ class ContextMenu {
         return li;
     }
     closeAllSubmenus(menu) {
-        // Only close direct-child submenus of this menu level
         Array.from(menu.children).forEach((child) => {
             child.classList.remove('is-active');
         });

package/js/datepicker.d.ts

@@ -1,7 +1,9 @@
+/** Localised day and month names for the DatePicker. */
 interface DatePickerLocales {
     days: string[];
     months: string[];
 }
+/** Configuration options for the DatePicker. */
 interface DatePickerOptions {
     mode?: 'single' | 'range';
     startDay?: number;
@@ -10,10 +12,12 @@ interface DatePickerOptions {
     format?: (date: Date) => string;
     onSelect?: (date: Date | DateRange) => void;
 }
+/** A date range with optional start and end dates. */
 interface DateRange {
     start: Date | null;
     end: Date | null;
 }
+/** Calendar-based date (or date-range) picker that attaches to an input element. */
 declare class DatePicker {
     private input;
     private options;

package/js/datepicker.js

@@ -1,6 +1,23 @@
+import { computePosition } from './position.js';
+/** Calendar-based date (or date-range) picker that attaches to an input element. */
 class DatePicker {
+    input;
+    options;
+    currentDate;
+    selectedDate;
+    rangeStart;
+    rangeEnd;
+    viewYear;
+    viewMonth;
+    viewMode;
+    yearRangeStart;
+    selectedHours;
+    selectedMinutes;
+    calendar;
+    backdrop;
+    handleDocumentClick;
+    abortController = new AbortController();
     constructor(elementOrSelector, options = {}) {
-        this.abortController = new AbortController();
         this.input = typeof elementOrSelector === 'string'
             ? document.querySelector(elementOrSelector)
             : elementOrSelector;
@@ -96,14 +113,14 @@ class DatePicker {
             this.backdrop.classList.remove('visible');
             document.body.style.overflow = '';
             if (this.input) {
-                const rect = this.input.getBoundingClientRect();
-                const scrollTop = window.pageYOffset || document.documentElement.scrollTop;
-                const scrollLeft = window.pageXOffset || document.documentElement.scrollLeft;
-                this.calendar.style.top = `${rect.bottom + scrollTop + 5}px`;
-                this.calendar.style.left = `${rect.left + scrollLeft}px`;
-                if (rect.left + 320 > window.innerWidth) {
-                    this.calendar.style.left = `${rect.right + scrollLeft - 320}px`;
-                }
+                this.calendar.style.display = 'block';
+                this.calendar.style.visibility = 'hidden';
+                const calRect = this.calendar.getBoundingClientRect();
+                this.calendar.style.display = '';
+                this.calendar.style.visibility = '';
+                const { left, top } = computePosition(this.input.getBoundingClientRect(), calRect, { placement: 'bottom', align: 'start', offset: 5 });
+                this.calendar.style.top = `${top}px`;
+                this.calendar.style.left = `${left}px`;
             }
             setTimeout(() => {
                 if (this.calendar.classList.contains('visible')) {
@@ -345,7 +362,6 @@ class DatePicker {
         wrapper.appendChild(label);
         const controls = document.createElement('div');
         controls.className = 'datepicker-time-controls';
-        // Hours spinner
         const hoursSpinner = this.createSpinner(this.selectedHours, 0, 23, (value) => {
             this.selectedHours = value;
             this.applyTimeToSelection();
@@ -353,7 +369,6 @@ class DatePicker {
         const separator = document.createElement('span');
         separator.className = 'datepicker-time-separator';
         separator.textContent = ':';
-        // Minutes spinner
         const minutesSpinner = this.createSpinner(this.selectedMinutes, 0, 59, (value) => {
             this.selectedMinutes = value;
             this.applyTimeToSelection();

package/js/dropdown.d.ts

@@ -1,11 +1,14 @@
+/** Configuration options for a Dropdown instance. */
 interface DropdownOptions {
     closeOnSelect?: boolean;
     allowMultipleOpen?: boolean;
 }
+/** Event detail payload for the `dropdown-select` custom event. */
 interface DropdownSelectDetail {
     text: string;
     element: HTMLElement;
 }
+/** Hierarchical dropdown menu with optional multi-open and close-on-select behaviour. */
 declare class Dropdown {
     private container;
     private trigger;
@@ -16,15 +19,13 @@ declare class Dropdown {
     private init;
     private attachEventListeners;
     private setupItems;
+    private updatePosition;
     toggle(): void;
     close(): void;
     open(): void;
     private toggleSubmenu;
     private closeAllSubmenus;
     private handleSelection;
-    /**
-     * Cleanup method to remove event listeners
-     */
     destroy(): void;
 }
 export { Dropdown, DropdownSelectDetail };

package/js/dropdown.js

@@ -1,4 +1,11 @@
+import { bestPlacement } from './position.js';
+/** Hierarchical dropdown menu with optional multi-open and close-on-select behaviour. */
 class Dropdown {
+    container;
+    trigger;
+    menu;
+    options;
+    abortController;
     constructor(selector, options = {}) {
         const container = document.querySelector(selector);
         if (!container) {
@@ -26,18 +33,15 @@ class Dropdown {
     }
     attachEventListeners() {
         const { signal } = this.abortController;
-        // Toggle main dropdown
         this.trigger.addEventListener('click', (e) => {
             e.stopPropagation();
             this.toggle();
         }, { signal });
-        // Close when clicking outside
         document.addEventListener('click', (e) => {
             if (!this.container.contains(e.target)) {
                 this.close();
             }
         }, { signal });
-        // Handle item clicks using event delegation
         this.menu.addEventListener('click', (e) => {
             e.stopPropagation();
             const target = e.target;
@@ -66,7 +70,16 @@ class Dropdown {
             }
         });
     }
+    updatePosition() {
+        const triggerRect = this.trigger.getBoundingClientRect();
+        const menuRect = this.menu.getBoundingClientRect();
+        const placement = bestPlacement(triggerRect, menuRect, 6);
+        this.container.classList.toggle('drop-up', placement === 'top');
+    }
     toggle() {
+        if (!this.container.classList.contains('active')) {
+            this.updatePosition();
+        }
         this.container.classList.toggle('active');
     }
     close() {
@@ -74,11 +87,11 @@ class Dropdown {
         this.closeAllSubmenus();
     }
     open() {
+        this.updatePosition();
         this.container.classList.add('active');
     }
     toggleSubmenu(li) {
         const isOpening = !li.classList.contains('open');
-        // Close siblings if not allowing multiple open menus
         if (isOpening && !this.options.allowMultipleOpen) {
             const parent = li.parentElement;
             if (parent) {
@@ -86,7 +99,6 @@ class Dropdown {
                 siblings.forEach((sibling) => {
                     if (sibling !== li && sibling.classList.contains('open')) {
                         sibling.classList.remove('open');
-                        // Close deeply nested open items
                         const deepOpenItems = sibling.querySelectorAll('.open');
                         deepOpenItems.forEach((el) => el.classList.remove('open'));
                     }
@@ -101,7 +113,6 @@ class Dropdown {
     }
     handleSelection(item) {
         const text = item.textContent?.trim() ?? '';
-        // Dispatch custom event with proper typing
         const event = new CustomEvent('dropdown-select', {
             detail: {
                 text,
@@ -111,9 +122,6 @@ class Dropdown {
         });
         this.container.dispatchEvent(event);
     }
-    /**
-     * Cleanup method to remove event listeners
-     */
     destroy() {
         this.abortController.abort();
         this.close();

package/js/editor.d.ts

@@ -3,6 +3,7 @@ interface EditorOptions {
      *  without #code, #preview, or #sidePanel in the DOM. */
     simple?: boolean;
 }
+/** Rich-text editor built on contenteditable with undo/redo and code/preview panels. */
 declare class Editor {
     private readonly editable;
     private readonly code;

package/js/editor.js

@@ -1,9 +1,15 @@
 import { sanitizeHtml } from './utils.js';
+/** Rich-text editor built on contenteditable with undo/redo and code/preview panels. */
 class Editor {
+    editable;
+    code;
+    preview;
+    sidePanel;
+    wordCount;
+    undoStack = [];
+    redoStack = [];
+    abortController = new AbortController();
     constructor(options = {}) {
-        this.undoStack = [];
-        this.redoStack = [];
-        this.abortController = new AbortController();
         const editable = document.getElementById('editable');
         if (!editable) {
             throw new Error('Editor: #editable element not found');

package/js/file-uploader.d.ts

@@ -1,17 +1,21 @@
+/** Event detail payload for the `upload-completed` custom event. */
 interface UploadCompletedDetail {
     fileCount: number;
     files: File[];
     results: PromiseSettledResult<unknown>[];
 }
+/** Event detail payload for the `file-validation-error` custom event. */
 interface FileValidationErrorDetail {
     file: File;
     reason: 'size' | 'type';
 }
+/** Configuration options for the FileUploader. */
 interface FileUploaderConfig {
     uploadUrl?: string;
     maxFileSize?: number;
     allowedTypes?: string[];
 }
+/** Drag-and-drop file uploader with progress tracking and XHR-based uploads. */
 declare class FileUploader {
     private container;
     private dropZone;