@dodlhuat/basix 1.2.0 → 1.2.1

package/js/popover.js

@@ -0,0 +1,163 @@
+import { computePosition } from './position.js';
+// Must match $arrow in popover.scss
+const ARROW_SIZE = 6;
+class Popover {
+    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;
+        if (!el)
+            throw new Error('Popover: trigger element not found');
+        this.trigger = el;
+        this.opts = {
+            content: options.content,
+            placement: options.placement ?? 'bottom',
+            align: options.align ?? 'center',
+            offset: options.offset ?? 8,
+            arrow: options.arrow ?? true,
+            triggerMode: options.triggerMode ?? 'click',
+            closeOnOutsideClick: options.closeOnOutsideClick ?? true,
+            closeOnEscape: options.closeOnEscape ?? true,
+            className: options.className ?? '',
+            onOpen: options.onOpen ?? (() => { }),
+            onClose: options.onClose ?? (() => { }),
+        };
+        this.attachTrigger();
+    }
+    // ── Public API ─────────────────────────────────────────────────────────────
+    get isOpen() { return this._isOpen; }
+    open() {
+        if (this._isOpen)
+            return;
+        if (this.opts.triggerMode === 'click')
+            Popover.closeAll();
+        this.popoverEl = this.buildEl();
+        document.body.appendChild(this.popoverEl);
+        this.reposition();
+        requestAnimationFrame(() => {
+            this.popoverEl?.classList.add('is-open');
+            this._isOpen = true;
+            Popover.openPopovers.add(this);
+            this.opts.onOpen();
+            if (this.opts.closeOnOutsideClick)
+                document.addEventListener('pointerdown', this.onOutsideClick, { capture: true });
+            if (this.opts.closeOnEscape)
+                document.addEventListener('keydown', this.onEscape);
+        });
+    }
+    close() {
+        if (!this._isOpen || !this.popoverEl)
+            return;
+        this.popoverEl.classList.remove('is-open');
+        this._isOpen = false;
+        Popover.openPopovers.delete(this);
+        this.opts.onClose();
+        document.removeEventListener('pointerdown', this.onOutsideClick, { capture: true });
+        document.removeEventListener('keydown', this.onEscape);
+        this.trigger.removeAttribute('aria-expanded');
+        this.trigger.removeAttribute('aria-controls');
+        const el = this.popoverEl;
+        setTimeout(() => el.remove(), 200);
+        this.popoverEl = null;
+    }
+    toggle() { this._isOpen ? this.close() : this.open(); }
+    destroy() {
+        this.close();
+        this.detachTrigger();
+    }
+    static closeAll() {
+        Popover.openPopovers.forEach(p => p.close());
+    }
+    /** Declarative init — reads [data-popover="#selector"] attributes */
+    static initAll() {
+        document.querySelectorAll('[data-popover]').forEach(trigger => {
+            const sel = trigger.getAttribute('data-popover');
+            if (!sel)
+                return;
+            const contentEl = document.querySelector(sel);
+            if (!contentEl)
+                return;
+            new Popover(trigger, {
+                content: contentEl.innerHTML,
+                placement: trigger.getAttribute('data-popover-placement') ?? 'bottom',
+                align: trigger.getAttribute('data-popover-align') ?? 'center',
+                triggerMode: trigger.getAttribute('data-popover-trigger') ?? 'click',
+                arrow: trigger.getAttribute('data-popover-arrow') !== 'false',
+            });
+        });
+    }
+    // ── Build ──────────────────────────────────────────────────────────────────
+    buildEl() {
+        const id = `popover-${++Popover.idCounter}`;
+        const el = document.createElement('div');
+        el.className = ['popover', this.opts.className].filter(Boolean).join(' ');
+        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);
+        el.innerHTML = hasStructure
+            ? this.opts.content
+            : `<div class="popover-body">${this.opts.content}</div>`;
+        this.trigger.setAttribute('aria-expanded', 'true');
+        this.trigger.setAttribute('aria-controls', id);
+        return el;
+    }
+    // ── Positioning ────────────────────────────────────────────────────────────
+    reposition() {
+        if (!this.popoverEl)
+            return;
+        const { left, top, placement, arrowOffset } = computePosition(this.trigger.getBoundingClientRect(), this.popoverEl.getBoundingClientRect(), {
+            placement: this.opts.placement,
+            align: this.opts.align,
+            offset: this.opts.offset,
+            arrowSize: this.opts.arrow ? ARROW_SIZE : undefined,
+        });
+        if (arrowOffset !== undefined)
+            this.popoverEl.style.setProperty('--popover-arrow-offset', `${arrowOffset}px`);
+        this.popoverEl.setAttribute('data-placement', placement);
+        this.popoverEl.setAttribute('data-align', this.opts.align);
+        this.popoverEl.style.left = `${left}px`;
+        this.popoverEl.style.top = `${top}px`;
+    }
+    attachTrigger() {
+        if (this.opts.triggerMode === 'click') {
+            this.trigger.addEventListener('click', this.onClick);
+        }
+        else {
+            this.trigger.addEventListener('mouseenter', this.onMouseEnter);
+            this.trigger.addEventListener('mouseleave', this.onMouseLeave);
+        }
+    }
+    detachTrigger() {
+        this.trigger.removeEventListener('click', this.onClick);
+        this.trigger.removeEventListener('mouseenter', this.onMouseEnter);
+        this.trigger.removeEventListener('mouseleave', this.onMouseLeave);
+    }
+}
+Popover.openPopovers = new Set();
+Popover.idCounter = 0;
+export { Popover };

package/js/popover.ts

@@ -0,0 +1,219 @@
+import { computePosition } from './position.js';
+import type { Placement } from './position.js';
+
+type PopoverPlacement = Placement | 'auto';
+type PopoverAlign     = 'start' | 'center' | 'end';
+type PopoverTrigger   = 'click' | 'hover';
+
+interface PopoverOptions {
+    content:              string;
+    placement?:           PopoverPlacement;
+    align?:               PopoverAlign;
+    offset?:              number;
+    arrow?:               boolean;
+    triggerMode?:         PopoverTrigger;
+    closeOnOutsideClick?: boolean;
+    closeOnEscape?:       boolean;
+    className?:           string;
+    onOpen?:              () => void;
+    onClose?:             () => void;
+}
+
+// Must match $arrow in popover.scss
+const ARROW_SIZE = 6;
+
+class Popover {
+    private static openPopovers: Set<Popover> = new Set();
+    private static idCounter = 0;
+
+    private readonly trigger: HTMLElement;
+    private readonly opts: Required<PopoverOptions>;
+    private popoverEl: HTMLElement | null = null;
+    private _isOpen = false;
+    private hoverTimer: number | null = null;
+
+    constructor(triggerEl: HTMLElement | string, options: PopoverOptions) {
+        const el = typeof triggerEl === 'string'
+            ? document.querySelector<HTMLElement>(triggerEl)
+            : triggerEl;
+        if (!el) throw new Error('Popover: trigger element not found');
+
+        this.trigger = el;
+        this.opts = {
+            content:              options.content,
+            placement:            options.placement            ?? 'bottom',
+            align:                options.align                ?? 'center',
+            offset:               options.offset               ?? 8,
+            arrow:                options.arrow                ?? true,
+            triggerMode:          options.triggerMode          ?? 'click',
+            closeOnOutsideClick:  options.closeOnOutsideClick  ?? true,
+            closeOnEscape:        options.closeOnEscape        ?? true,
+            className:            options.className            ?? '',
+            onOpen:               options.onOpen               ?? (() => {}),
+            onClose:              options.onClose              ?? (() => {}),
+        };
+
+        this.attachTrigger();
+    }
+
+    // ── Public API ─────────────────────────────────────────────────────────────
+
+    get isOpen(): boolean { return this._isOpen; }
+
+    open(): void {
+        if (this._isOpen) return;
+        if (this.opts.triggerMode === 'click') Popover.closeAll();
+
+        this.popoverEl = this.buildEl();
+        document.body.appendChild(this.popoverEl);
+        this.reposition();
+
+        requestAnimationFrame(() => {
+            this.popoverEl?.classList.add('is-open');
+            this._isOpen = true;
+            Popover.openPopovers.add(this);
+            this.opts.onOpen();
+
+            if (this.opts.closeOnOutsideClick)
+                document.addEventListener('pointerdown', this.onOutsideClick, { capture: true });
+            if (this.opts.closeOnEscape)
+                document.addEventListener('keydown', this.onEscape);
+        });
+    }
+
+    close(): void {
+        if (!this._isOpen || !this.popoverEl) return;
+
+        this.popoverEl.classList.remove('is-open');
+        this._isOpen = false;
+        Popover.openPopovers.delete(this);
+        this.opts.onClose();
+
+        document.removeEventListener('pointerdown', this.onOutsideClick, { capture: true });
+        document.removeEventListener('keydown', this.onEscape);
+
+        this.trigger.removeAttribute('aria-expanded');
+        this.trigger.removeAttribute('aria-controls');
+
+        const el = this.popoverEl;
+        setTimeout(() => el.remove(), 200);
+        this.popoverEl = null;
+    }
+
+    toggle(): void { this._isOpen ? this.close() : this.open(); }
+
+    destroy(): void {
+        this.close();
+        this.detachTrigger();
+    }
+
+    static closeAll(): void {
+        Popover.openPopovers.forEach(p => p.close());
+    }
+
+    /** Declarative init — reads [data-popover="#selector"] attributes */
+    static initAll(): void {
+        document.querySelectorAll<HTMLElement>('[data-popover]').forEach(trigger => {
+            const sel = trigger.getAttribute('data-popover');
+            if (!sel) return;
+            const contentEl = document.querySelector(sel);
+            if (!contentEl) return;
+
+            new Popover(trigger, {
+                content:    (contentEl as HTMLElement).innerHTML,
+                placement:  (trigger.getAttribute('data-popover-placement') as PopoverPlacement) ?? 'bottom',
+                align:      (trigger.getAttribute('data-popover-align')     as PopoverAlign)     ?? 'center',
+                triggerMode:(trigger.getAttribute('data-popover-trigger')   as PopoverTrigger)   ?? 'click',
+                arrow:       trigger.getAttribute('data-popover-arrow')     !== 'false',
+            });
+        });
+    }
+
+    // ── Build ──────────────────────────────────────────────────────────────────
+
+    private buildEl(): HTMLElement {
+        const id = `popover-${++Popover.idCounter}`;
+        const el  = document.createElement('div');
+        el.className   = ['popover', this.opts.className].filter(Boolean).join(' ');
+        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);
+        el.innerHTML = hasStructure
+            ? this.opts.content
+            : `<div class="popover-body">${this.opts.content}</div>`;
+
+        this.trigger.setAttribute('aria-expanded', 'true');
+        this.trigger.setAttribute('aria-controls', id);
+
+        return el;
+    }
+
+    // ── Positioning ────────────────────────────────────────────────────────────
+
+    private reposition(): void {
+        if (!this.popoverEl) return;
+
+        const { left, top, placement, arrowOffset } = computePosition(
+            this.trigger.getBoundingClientRect(),
+            this.popoverEl.getBoundingClientRect(),
+            {
+                placement: this.opts.placement,
+                align:     this.opts.align,
+                offset:    this.opts.offset,
+                arrowSize: this.opts.arrow ? ARROW_SIZE : undefined,
+            }
+        );
+
+        if (arrowOffset !== undefined)
+            this.popoverEl.style.setProperty('--popover-arrow-offset', `${arrowOffset}px`);
+
+        this.popoverEl.setAttribute('data-placement', placement);
+        this.popoverEl.setAttribute('data-align', this.opts.align);
+        this.popoverEl.style.left = `${left}px`;
+        this.popoverEl.style.top  = `${top}px`;
+    }
+
+    // ── Event handlers ─────────────────────────────────────────────────────────
+
+    private onClick = (): void => { this.toggle(); };
+
+    private onMouseEnter = (): void => {
+        if (this.hoverTimer !== null) clearTimeout(this.hoverTimer);
+        this.open();
+    };
+
+    private onMouseLeave = (): void => {
+        this.hoverTimer = window.setTimeout(() => this.close(), 120);
+    };
+
+    private onOutsideClick = (e: Event): void => {
+        const t = e.target as Node;
+        if (!this.popoverEl?.contains(t) && !this.trigger.contains(t)) this.close();
+    };
+
+    private onEscape = (e: KeyboardEvent): void => {
+        if (e.key === 'Escape') this.close();
+    };
+
+    private attachTrigger(): void {
+        if (this.opts.triggerMode === 'click') {
+            this.trigger.addEventListener('click', this.onClick);
+        } else {
+            this.trigger.addEventListener('mouseenter', this.onMouseEnter);
+            this.trigger.addEventListener('mouseleave', this.onMouseLeave);
+        }
+    }
+
+    private detachTrigger(): void {
+        this.trigger.removeEventListener('click', this.onClick);
+        this.trigger.removeEventListener('mouseenter', this.onMouseEnter);
+        this.trigger.removeEventListener('mouseleave', this.onMouseLeave);
+    }
+}
+
+export { Popover };
+export type { PopoverOptions, PopoverPlacement, PopoverAlign, PopoverTrigger };

package/js/position.js

@@ -0,0 +1,108 @@
+/**
+ * Shared floating-element positioning utility.
+ * Used by Tooltip and Popover.
+ */
+/** Pick the placement with the most available space, preferring bottom > top > right > left. */
+function bestPlacement(trigger, floating, offset) {
+    const space = {
+        bottom: window.innerHeight - trigger.bottom - offset,
+        top: trigger.top - offset,
+        right: window.innerWidth - trigger.right - offset,
+        left: trigger.left - offset,
+    };
+    if (space.bottom >= floating.height)
+        return 'bottom';
+    if (space.top >= floating.height)
+        return 'top';
+    if (space.right >= floating.width)
+        return 'right';
+    if (space.left >= floating.width)
+        return 'left';
+    // Fallback: largest available side
+    return (Object.entries(space).sort((a, b) => b[1] - a[1])[0][0]);
+}
+/** Flip to opposite side if preferred placement doesn't fit. */
+function maybeFlip(placement, trigger, floating, offset) {
+    const fits = {
+        top: trigger.top - offset >= floating.height,
+        bottom: window.innerHeight - trigger.bottom - offset >= floating.height,
+        left: trigger.left - offset >= floating.width,
+        right: window.innerWidth - trigger.right - offset >= floating.width,
+    };
+    const opp = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' };
+    return (!fits[placement] && fits[opp[placement]]) ? opp[placement] : placement;
+}
+/**
+ * Compute `left` / `top` for a `position: fixed` floating element anchored to a trigger.
+ * Handles placement resolution (auto + flip), cross-axis alignment, viewport clamping,
+ * and optional arrow offset calculation.
+ */
+function computePosition(trigger, floating, opts) {
+    const offset = opts.offset ?? 8;
+    const margin = opts.margin ?? 8;
+    const align = opts.align ?? 'center';
+    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':
+            top = trigger.top - floating.height - offset;
+            break;
+        case 'bottom':
+            top = trigger.bottom + offset;
+            break;
+        case 'left':
+            left = trigger.left - floating.width - offset;
+            break;
+        case 'right':
+            left = trigger.right + offset;
+            break;
+    }
+    // Cross-axis alignment
+    if (placement === 'top' || placement === 'bottom') {
+        switch (align) {
+            case 'start':
+                left = trigger.left;
+                break;
+            case 'center':
+                left = trigger.left + (trigger.width - floating.width) / 2;
+                break;
+            case 'end':
+                left = trigger.right - floating.width;
+                break;
+        }
+    }
+    else {
+        switch (align) {
+            case 'start':
+                top = trigger.top;
+                break;
+            case 'center':
+                top = trigger.top + (trigger.height - floating.height) / 2;
+                break;
+            case 'end':
+                top = trigger.bottom - floating.height;
+                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
+        if (placement === 'top' || placement === 'bottom') {
+            const raw = trigger.left + trigger.width / 2 - l;
+            arrowOffset = Math.max(minOff, Math.min(floating.width - minOff, raw));
+        }
+        else {
+            const raw = trigger.top + trigger.height / 2 - t;
+            arrowOffset = Math.max(minOff, Math.min(floating.height - minOff, raw));
+        }
+    }
+    return { left: l, top: t, placement, arrowOffset };
+}
+export { computePosition, bestPlacement, maybeFlip };

package/js/position.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared floating-element positioning utility.
+ * Used by Tooltip and Popover.
+ */
+
+type Placement = 'top' | 'bottom' | 'left' | 'right';
+type Align     = 'start' | 'center' | 'end';
+
+interface PositionOptions {
+    placement:      Placement | 'auto';
+    align?:         Align;
+    offset?:        number;  // gap between trigger and floating element (default: 8)
+    margin?:        number;  // minimum distance from viewport edge (default: 8)
+    arrowSize?:     number;  // if set, returns arrowOffset in result
+}
+
+interface PositionResult {
+    left:         number;
+    top:          number;
+    placement:    Placement;   // resolved (after auto/flip)
+    arrowOffset?: number;      // px offset for arrow centering on trigger axis
+}
+
+/** Pick the placement with the most available space, preferring bottom > top > right > left. */
+function bestPlacement(trigger: DOMRect, floating: DOMRect, offset: number): Placement {
+    const space = {
+        bottom: window.innerHeight - trigger.bottom - offset,
+        top:    trigger.top        - offset,
+        right:  window.innerWidth  - trigger.right  - offset,
+        left:   trigger.left       - offset,
+    };
+    if (space.bottom >= floating.height) return 'bottom';
+    if (space.top    >= floating.height) return 'top';
+    if (space.right  >= floating.width)  return 'right';
+    if (space.left   >= floating.width)  return 'left';
+    // Fallback: largest available side
+    return (Object.entries(space).sort((a, b) => b[1] - a[1])[0][0]) as Placement;
+}
+
+/** Flip to opposite side if preferred placement doesn't fit. */
+function maybeFlip(placement: Placement, trigger: DOMRect, floating: DOMRect, offset: number): Placement {
+    const fits: Record<Placement, boolean> = {
+        top:    trigger.top        - offset >= floating.height,
+        bottom: window.innerHeight - trigger.bottom - offset >= floating.height,
+        left:   trigger.left       - offset >= floating.width,
+        right:  window.innerWidth  - trigger.right  - offset >= floating.width,
+    };
+    const opp: Record<Placement, Placement> = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' };
+    return (!fits[placement] && fits[opp[placement]]) ? opp[placement] : placement;
+}
+
+/**
+ * Compute `left` / `top` for a `position: fixed` floating element anchored to a trigger.
+ * Handles placement resolution (auto + flip), cross-axis alignment, viewport clamping,
+ * and optional arrow offset calculation.
+ */
+function computePosition(trigger: DOMRect, floating: DOMRect, opts: PositionOptions): PositionResult {
+    const offset = opts.offset ?? 8;
+    const margin = opts.margin ?? 8;
+    const align  = opts.align  ?? 'center';
+
+    const placement: 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':    top  = trigger.top    - floating.height - offset; break;
+        case 'bottom': top  = trigger.bottom + offset;                    break;
+        case 'left':   left = trigger.left   - floating.width  - offset; break;
+        case 'right':  left = trigger.right  + offset;                   break;
+    }
+
+    // Cross-axis alignment
+    if (placement === 'top' || placement === 'bottom') {
+        switch (align) {
+            case 'start':  left = trigger.left;                                          break;
+            case 'center': left = trigger.left + (trigger.width  - floating.width)  / 2; break;
+            case 'end':    left = trigger.right - floating.width;                        break;
+        }
+    } else {
+        switch (align) {
+            case 'start':  top = trigger.top;                                             break;
+            case 'center': top = trigger.top  + (trigger.height - floating.height) / 2;  break;
+            case 'end':    top = trigger.bottom - floating.height;                        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: number | undefined;
+    if (opts.arrowSize !== undefined) {
+        const minOff = opts.arrowSize + 8; // min distance from rounded corner
+        if (placement === 'top' || placement === 'bottom') {
+            const raw = trigger.left + trigger.width  / 2 - l;
+            arrowOffset = Math.max(minOff, Math.min(floating.width  - minOff, raw));
+        } else {
+            const raw = trigger.top  + trigger.height / 2 - t;
+            arrowOffset = Math.max(minOff, Math.min(floating.height - minOff, raw));
+        }
+    }
+
+    return { left: l, top: t, placement, arrowOffset };
+}
+
+export { computePosition, bestPlacement, maybeFlip };
+export type { Placement, Align, PositionOptions, PositionResult };