@phillipsharring/graspr-framework 0.1.0

package/src/ui/modal-form.js

@@ -0,0 +1,162 @@
+// ---------------------------
+// Modal Form Utility
+// ---------------------------
+// Provides a unified way to open forms in the global modal.
+
+import Handlebars from 'handlebars';
+import htmx from '../lib/htmx.js';
+import { openGlobalModal } from './modal.js';
+
+/**
+ * Opens a form in the global modal with the given configuration.
+ *
+ * @param {Object} config - Configuration object
+ * @param {string} config.templateId - ID of the template element (without #)
+ * @param {string} config.title - Modal title text
+ * @param {string} [config.formUrl] - URL to set on form's hx-patch/hx-post and action attributes
+ * @param {'post'|'patch'} [config.formMethod] - HTTP method for the form
+ * @param {Object} [config.fields] - Object mapping field names to values to populate
+ * @param {string[]} [config.removeFields] - Array of field names to remove from the form
+ * @param {string} [config.submitButtonText] - Text to set on the submit button
+ * @param {boolean} [config.clearErrors=true] - Whether to clear existing form errors
+ * @param {string} [config.focusSelector] - Selector for element to focus (defaults to first input)
+ * @param {function} [config.beforeOpen] - Callback(content, form) for custom setup before modal opens
+ * @param {'sm'|'takeover'|'default'} [config.size] - Modal size variant
+ */
+export function openFormModal({
+    templateId,
+    title,
+    formUrl,
+    formMethod,
+    fields,
+    removeFields,
+    submitButtonText,
+    clearErrors = true,
+    focusSelector,
+    beforeOpen,
+    size,
+}) {
+    const template = document.getElementById(templateId);
+    const content = document.getElementById('global-modal-content');
+    const dialog = document.querySelector('#global-modal [role="dialog"]');
+    const titleEl = document.getElementById('global-modal-title');
+
+    if (!template || !content) {
+        console.error('openFormModal: template or modal content not found', { templateId });
+        return;
+    }
+
+    // Set modal title
+    if (titleEl) {
+        titleEl.textContent = title;
+    }
+
+    // Set modal size
+    const modal = document.getElementById('global-modal');
+    if (dialog) {
+        dialog.classList.remove('modal-sm', 'modal-lg');
+        if (size === 'sm') {
+            dialog.classList.add('modal-sm');
+        } else if (size === 'lg') {
+            dialog.classList.add('modal-lg');
+        }
+    }
+    if (modal) {
+        modal.classList.remove('modal-takeover');
+        if (size === 'takeover') {
+            modal.classList.add('modal-takeover');
+        }
+    }
+
+    // Inject template HTML — compile through Handlebars to resolve partials
+    // (e.g. {{> formButtons}}). innerHTML escapes ">" to ">" per the HTML
+    // serialization spec, so unescape partial calls first.
+    const source = template.innerHTML.replaceAll('{{>', '{{>');
+    content.innerHTML = Handlebars.compile(source)({});
+
+    // Find the form
+    const form = content.querySelector('form');
+
+    if (form) {
+        // Set form URL and method if provided
+        if (formUrl) {
+            if (formMethod === 'patch') {
+                form.removeAttribute('hx-post');
+                form.setAttribute('hx-patch', formUrl);
+                form.setAttribute('method', 'patch');
+            } else if (formMethod === 'post') {
+                form.removeAttribute('hx-patch');
+                form.setAttribute('hx-post', formUrl);
+                form.setAttribute('method', 'post');
+            }
+            form.setAttribute('action', formUrl);
+        }
+
+        // Remove specified fields
+        if (removeFields && Array.isArray(removeFields)) {
+            for (const fieldName of removeFields) {
+                const field = form.querySelector(`[name="${fieldName}"]`);
+                if (field) {
+                    field.remove();
+                }
+            }
+        }
+
+        // Populate fields
+        if (fields && typeof fields === 'object') {
+            for (const [name, value] of Object.entries(fields)) {
+                const input = form.querySelector(`[name="${name}"]`);
+                if (input) {
+                    if (input.tagName === 'TEXTAREA') {
+                        input.value = value || '';
+                    } else if (input.tagName === 'INPUT') {
+                        input.value = value || '';
+                    } else if (input.tagName === 'SELECT') {
+                        input.value = value || '';
+                    }
+                }
+            }
+        }
+
+        // Update submit button text if provided
+        if (submitButtonText) {
+            const submitBtn = form.querySelector('button[type="submit"]');
+            if (submitBtn) {
+                submitBtn.textContent = submitButtonText;
+            }
+        }
+
+        // Clear form errors if requested
+        if (clearErrors) {
+            content.querySelectorAll('.field-error-text').forEach((el) => {
+                el.textContent = '';
+                el.classList.add('hidden');
+            });
+            content.querySelectorAll('.form-field').forEach((el) => {
+                el.classList.remove('has-error');
+            });
+            content.querySelectorAll('.field-error').forEach((el) => {
+                el.classList.remove('field-error');
+            });
+        }
+
+        // Call custom setup callback if provided
+        if (typeof beforeOpen === 'function') {
+            beforeOpen(content, form);
+        }
+    }
+
+    // Process HTMX attributes
+    htmx.process(content);
+
+    // Open the modal
+    openGlobalModal();
+
+    // Focus the appropriate element
+    const focusTarget = focusSelector
+        ? content.querySelector(focusSelector)
+        : content.querySelector('input, select, textarea, button');
+    if (focusTarget) {
+        focusTarget.focus();
+    }
+}

package/src/ui/modal.js

@@ -0,0 +1,127 @@
+// ---------------------------
+// Global Modal
+// ---------------------------
+
+let lastFocusBeforeModal = null;
+
+// Callback for when modal is closed while confirm is active
+let onModalCloseWithConfirm = null;
+
+export function setOnModalCloseWithConfirm(callback) {
+    onModalCloseWithConfirm = callback;
+}
+
+export function getGlobalModal() {
+    return document.getElementById('global-modal');
+}
+
+export function getGlobalModalDialog() {
+    return document.querySelector('#global-modal [role="dialog"]');
+}
+
+export function getGlobalModalHeader() {
+    return document.getElementById('global-modal-header');
+}
+
+export function getGlobalModalCloseButton() {
+    return document.getElementById('global-modal-close-btn');
+}
+
+export function isGlobalModalOpen() {
+    const modal = getGlobalModal();
+    return !!modal && modal.classList.contains('modal-open');
+}
+
+export function openGlobalModal(options = {}) {
+    const modal = getGlobalModal();
+    if (!modal) return;
+    lastFocusBeforeModal = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    // Clear inline styles used to prevent flash of content on page load
+    modal.removeAttribute('style');
+
+    // Apply takeover mode if requested
+    if (options.takeover) {
+        modal.classList.add('modal-takeover');
+    }
+
+    modal.classList.add('modal-open');
+    modal.setAttribute('aria-hidden', 'false');
+    document.body.classList.add('overflow-hidden');
+
+    const dialog = getGlobalModalDialog();
+    if (dialog instanceof HTMLElement) {
+        // Defer to ensure it's visible before focusing
+        queueMicrotask(() => dialog.focus());
+    }
+}
+
+export function closeGlobalModal() {
+    const modal = getGlobalModal();
+    if (!modal) return;
+
+    // If a confirm dialog is active, closing the modal counts as "cancel".
+    if (onModalCloseWithConfirm) {
+        onModalCloseWithConfirm();
+    }
+
+    // Avoid hiding a focused element from assistive tech (prevents aria-hidden warning).
+    const active = document.activeElement;
+    if (active instanceof HTMLElement && modal.contains(active)) {
+        active.blur();
+    }
+
+    // Check if takeover mode before removing modal-open
+    const wasTakeover = modal.classList.contains('modal-takeover');
+
+    modal.classList.remove('modal-open');
+    modal.setAttribute('aria-hidden', 'true');
+    document.body.classList.remove('overflow-hidden');
+
+    // Dispatch event so listeners can react (e.g. refresh widgets after pack opening)
+    document.dispatchEvent(new CustomEvent('modal:closed', { detail: { takeover: wasTakeover } }));
+
+    // Delay cleanup of size/mode classes until after transition completes
+    // to prevent flash of default modal style
+    setTimeout(() => {
+        modal.classList.remove('modal-takeover');
+        const header = getGlobalModalHeader();
+        if (header) header.style.display = '';
+        const dialog = getGlobalModalDialog();
+        if (dialog) {
+            dialog.classList.remove('modal-sm', 'modal-lg', 'confirm-mode');
+        }
+    }, wasTakeover ? 200 : 150);
+
+    if (lastFocusBeforeModal && document.contains(lastFocusBeforeModal)) {
+        queueMicrotask(() => lastFocusBeforeModal?.focus());
+    }
+    lastFocusBeforeModal = null;
+}
+
+// ---------------------------
+// Event Listeners
+// ---------------------------
+
+// Close modal on overlay click / close button click (anything with data-modal-close)
+document.addEventListener('click', (e) => {
+    const closeBtn = e.target.closest('[data-modal-close]');
+    if (!closeBtn) return;
+
+    // In takeover mode, only explicit close buttons work (not backdrop clicks)
+    const modal = getGlobalModal();
+    if (modal?.classList.contains('modal-takeover')) {
+        // Check if this is the backdrop overlay (not an explicit close button)
+        if (closeBtn.classList.contains('absolute') && closeBtn.classList.contains('inset-0')) {
+            return; // Ignore backdrop clicks in takeover mode
+        }
+    }
+
+    closeGlobalModal();
+});
+
+// Close modal on Escape
+document.addEventListener('keydown', (e) => {
+    if (e.key !== 'Escape') return;
+    if (!isGlobalModalOpen()) return;
+    closeGlobalModal();
+});

package/src/ui/toast.js

@@ -0,0 +1,126 @@
+/**
+ * Toast notification system
+ */
+
+import Handlebars from 'handlebars';
+
+let toastHideTimer = null;
+const DEFAULT_TOAST_MS = 5_000;
+let lastFocusBeforeToast = null;
+let toastTransitionTimer = null;
+const TOAST_TRANSITION_MS = 200;
+
+function getToastWrap() {
+    return document.getElementById('global-toast-wrap');
+}
+
+function openToast({ timeoutMs = DEFAULT_TOAST_MS } = {}) {
+    const wrap = getToastWrap();
+    if (!wrap) return;
+
+    lastFocusBeforeToast = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    if (toastTransitionTimer) window.clearTimeout(toastTransitionTimer);
+    wrap.classList.remove('hidden');
+    wrap.setAttribute('aria-hidden', 'false');
+
+    // Fade in: ensure the "from" styles are applied before switching to "to" styles.
+    wrap.classList.add('opacity-0', 'translate-y-2');
+    wrap.classList.remove('opacity-100', 'translate-y-0');
+    // Force layout so the browser commits the initial state (prevents "just appears").
+    void wrap.getBoundingClientRect();
+    wrap.classList.remove('opacity-0', 'translate-y-2');
+    wrap.classList.add('opacity-100', 'translate-y-0');
+
+    if (toastHideTimer) window.clearTimeout(toastHideTimer);
+    toastHideTimer = window.setTimeout(() => closeToast(), timeoutMs);
+}
+
+function closeToast() {
+    const wrap = getToastWrap();
+    if (!wrap) return;
+
+    // Avoid hiding a focused element from assistive tech (prevents aria-hidden warning).
+    const active = document.activeElement;
+    if (active instanceof HTMLElement && wrap.contains(active)) {
+        active.blur();
+    }
+
+    if (toastHideTimer) window.clearTimeout(toastHideTimer);
+    toastHideTimer = null;
+
+    if (lastFocusBeforeToast && document.contains(lastFocusBeforeToast)) {
+        queueMicrotask(() => lastFocusBeforeToast?.focus());
+    }
+    lastFocusBeforeToast = null;
+
+    // Fade out, then fully hide
+    if (toastTransitionTimer) window.clearTimeout(toastTransitionTimer);
+    wrap.classList.remove('opacity-100', 'translate-y-0');
+    wrap.classList.add('opacity-0', 'translate-y-2');
+    toastTransitionTimer = window.setTimeout(() => {
+        wrap.classList.add('hidden');
+        wrap.setAttribute('aria-hidden', 'true');
+        toastTransitionTimer = null;
+    }, TOAST_TRANSITION_MS);
+}
+
+function renderToastHtml(data) {
+    const tpl = document.getElementById('global-toast-template');
+    if (!(tpl instanceof HTMLTemplateElement)) return null;
+    const html = tpl.innerHTML;
+    const render = Handlebars.compile(html);
+    return render(data || {});
+}
+
+// Public API
+export const GrasprToast = {
+    show({ message, status = 'success', timeoutMs = DEFAULT_TOAST_MS } = {}) {
+        const wrap = getToastWrap();
+        const content = document.getElementById('global-toast-content');
+        if (!wrap || !content) return;
+        const html = renderToastHtml({ message, status });
+        if (html) content.innerHTML = html;
+        openToast({ timeoutMs });
+    },
+    close: closeToast,
+};
+
+// Handlebars helper for toast styling
+export function registerToastHelpers(Handlebars) {
+    Handlebars.registerHelper('toastClass', (status) => {
+        const s = String(status || 'success').toLowerCase();
+        // Note: accept the user's typo "eror" as error.
+        const normalized = s === 'eror' ? 'error' : s;
+
+        switch (normalized) {
+            case 'warning':
+                return 'bg-amber-100 text-amber-900 border-amber-200';
+            case 'error':
+                return 'bg-red-600 text-white border-red-700';
+            case 'success':
+            default:
+                return 'bg-green-600 text-white border-green-700';
+        }
+    });
+}
+
+// Toast event handlers
+export function initToastEventHandlers() {
+    // Close toast on dismiss button
+    document.addEventListener('click', (e) => {
+        const closeBtn = e.target.closest('[data-toast-close]');
+        if (!closeBtn) return;
+        closeToast();
+    });
+
+    // Auto-show toast when HTMX swaps content into the toast container
+    document.body.addEventListener('htmx:afterSwap', (e) => {
+        const target = e.detail?.target;
+        if (target && target.id === 'global-toast-content') {
+            openToast();
+        }
+    });
+}
+
+// Internal exports for use by other modules
+export { openToast, closeToast };

package/src/ui/typeahead.js

@@ -0,0 +1,186 @@
+import { escapeHtml } from '../helpers/escape-html.js';
+
+/**
+ * Reusable typeahead/autocomplete widget factory.
+ *
+ * @param {Object} options
+ * @param {Element} options.input - text input element
+ * @param {Element} options.dropdown - dropdown container element
+ * @param {Function} options.onSelect - called with the selected item
+ * @param {Array} [options.items] - searchable items (each should have .name)
+ * @param {Function} [options.renderItem] - (item) → innerHTML string
+ * @param {Function} [options.filterItem] - (item, query) → boolean
+ * @param {Array} [options.prependItems] - items always prepended to results
+ * @param {string|null} [options.noMatchText] - text when no results; null hides dropdown
+ * @param {number} [options.minQueryLength] - 0 = show all on empty, 1+ = require chars
+ * @param {number} [options.debounceMs] - debounce input events
+ * @param {boolean} [options.clearOnSelect] - clear input after selection
+ * @param {Element} [options.closeParent] - for outside-click detection
+ * @returns {{ setItems: Function, destroy: Function }}
+ */
+export function createTypeahead({
+    input,
+    dropdown,
+    onSelect,
+    items = [],
+    renderItem,
+    filterItem,
+    prependItems = [],
+    noMatchText = 'No matches',
+    minQueryLength = 1,
+    debounceMs = 0,
+    clearOnSelect = false,
+    closeParent,
+}) {
+    var highlightIndex = -1;
+    var debounceTimer = null;
+
+    if (!renderItem) {
+        renderItem = function(item) { return escapeHtml(item.name); };
+    }
+    if (!filterItem) {
+        filterItem = function(item, query) {
+            return item.name.toLowerCase().indexOf(query) !== -1;
+        };
+    }
+
+    function getFiltered() {
+        var query = input.value.trim().toLowerCase();
+        var matches = query
+            ? items.filter(function(item) { return filterItem(item, query); })
+            : items;
+        return prependItems.concat(matches);
+    }
+
+    function render() {
+        var query = input.value.trim().toLowerCase();
+        if (query.length < minQueryLength) {
+            hide();
+            return;
+        }
+
+        var filtered = getFiltered();
+
+        if (filtered.length === 0) {
+            if (noMatchText) {
+                dropdown.innerHTML = '<div class="px-3 py-2 text-sm text-slate-400">' + escapeHtml(noMatchText) + '</div>';
+                dropdown.classList.remove('hidden');
+            } else {
+                hide();
+            }
+            highlightIndex = -1;
+            return;
+        }
+
+        var html = '';
+        filtered.forEach(function(item, i) {
+            html += '<div class="px-3 py-2 text-sm cursor-pointer hover:bg-slate-100" data-ta-index="' + i + '">';
+            html += renderItem(item);
+            html += '</div>';
+        });
+        dropdown.innerHTML = html;
+        dropdown.classList.remove('hidden');
+        highlightIndex = -1;
+
+        // Mousedown (not click) so input keeps focus
+        dropdown.querySelectorAll('[data-ta-index]').forEach(function(el) {
+            el.addEventListener('mousedown', function(e) {
+                e.preventDefault();
+                select(filtered[parseInt(el.dataset.taIndex, 10)]);
+            });
+        });
+    }
+
+    function highlight() {
+        var els = dropdown.querySelectorAll('[data-ta-index]');
+        els.forEach(function(el, i) {
+            if (i === highlightIndex) {
+                el.classList.add('bg-slate-100');
+                el.scrollIntoView({ block: 'nearest' });
+            } else {
+                el.classList.remove('bg-slate-100');
+            }
+        });
+    }
+
+    function hide() {
+        dropdown.classList.add('hidden');
+        highlightIndex = -1;
+    }
+
+    function select(item) {
+        hide();
+        if (clearOnSelect) input.value = '';
+        onSelect(item);
+    }
+
+    function onInput() {
+        if (debounceMs > 0) {
+            clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(render, debounceMs);
+        } else {
+            render();
+        }
+    }
+
+    function onFocus() {
+        if (input.value.trim().length >= minQueryLength) {
+            render();
+        }
+    }
+
+    function onKeydown(e) {
+        if (dropdown.classList.contains('hidden')) {
+            if (e.key === 'ArrowDown' && minQueryLength === 0) {
+                e.preventDefault();
+                render();
+            }
+            return;
+        }
+
+        var els = dropdown.querySelectorAll('[data-ta-index]');
+        if (els.length === 0) return;
+
+        if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            highlightIndex = Math.min(highlightIndex + 1, els.length - 1);
+            highlight();
+        } else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            highlightIndex = Math.max(highlightIndex - 1, 0);
+            highlight();
+        } else if (e.key === 'Enter') {
+            if (highlightIndex >= 0 && highlightIndex < els.length) {
+                e.preventDefault();
+                var filtered = getFiltered();
+                select(filtered[highlightIndex]);
+            }
+        } else if (e.key === 'Escape') {
+            hide();
+        }
+    }
+
+    function onOutsideClick(e) {
+        if (!input.contains(e.target) && !dropdown.contains(e.target)) {
+            hide();
+        }
+    }
+
+    input.addEventListener('input', onInput);
+    input.addEventListener('focus', onFocus);
+    input.addEventListener('keydown', onKeydown);
+
+    var clickTarget = closeParent || document;
+    clickTarget.addEventListener('click', onOutsideClick);
+
+    return {
+        setItems: function(newItems) { items = newItems; },
+        destroy: function() {
+            input.removeEventListener('input', onInput);
+            input.removeEventListener('focus', onFocus);
+            input.removeEventListener('keydown', onKeydown);
+            clickTarget.removeEventListener('click', onOutsideClick);
+            clearTimeout(debounceTimer);
+        },
+    };
+}