decantr 0.9.0

package/src/components/datetime-picker.js

@@ -0,0 +1,271 @@
+/**
+ * DateTimePicker — Combined date + time selection returning ISO datetime string.
+ * Composes DatePicker + TimePicker internally.
+ *
+ * @module decantr/components/datetime-picker
+ */
+import { onDestroy } from '../core/index.js';
+import { createEffect } from '../state/index.js';
+import { tags } from '../tags/index.js';
+import { injectBase, cx } from './_base.js';
+import { caret, createOverlay } from './_behaviors.js';
+import { icon } from './icon.js';
+
+const { div, span, button: buttonTag, input } = tags;
+
+const DAYS_HDR = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/**
+ * @param {Object} [props]
+ * @param {Date|string|Function} [props.value] - Selected datetime (Date or ISO string)
+ * @param {string} [props.placeholder='Select date and time']
+ * @param {Date} [props.min] - Minimum selectable datetime
+ * @param {Date} [props.max] - Maximum selectable datetime
+ * @param {boolean} [props.seconds=false] - Show seconds in time picker
+ * @param {boolean} [props.use12h=false] - 12-hour format
+ * @param {boolean|Function} [props.disabled]
+ * @param {Function} [props.onchange] - Called with Date object
+ * @param {string} [props.class]
+ * @returns {HTMLElement}
+ */
+export function DateTimePicker(props = {}) {
+  injectBase();
+  const {
+    value, placeholder = 'Select date and time',
+    min, max, seconds = false, use12h = false,
+    disabled, onchange, class: cls
+  } = props;
+
+  let selected = parseVal(typeof value === 'function' ? value() : value);
+  let viewDate = selected ? new Date(selected) : new Date();
+  let _h = selected ? selected.getHours() : 12;
+  let _m = selected ? selected.getMinutes() : 0;
+  let _s = selected ? selected.getSeconds() : 0;
+
+  function parseVal(v) {
+    if (!v) return null;
+    if (v instanceof Date) return v;
+    const d = new Date(v);
+    return isNaN(d) ? null : d;
+  }
+
+  function formatDisplay(d) {
+    if (!d) return '';
+    const y = d.getFullYear();
+    const mo = String(d.getMonth() + 1).padStart(2, '0');
+    const day = String(d.getDate()).padStart(2, '0');
+    let h = d.getHours(), period = '';
+    if (use12h) {
+      period = h >= 12 ? ' PM' : ' AM';
+      h = h % 12 || 12;
+    }
+    const time = `${String(h).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}${seconds ? ':' + String(d.getSeconds()).padStart(2, '0') : ''}${period}`;
+    return `${y}-${mo}-${day} ${time}`;
+  }
+
+  function buildDateTime(date, hours, mins, secs) {
+    const d = new Date(date);
+    d.setHours(hours, mins, secs, 0);
+    return d;
+  }
+
+  // Display
+  const displayEl = span({ class: 'd-select-display' });
+  const arrow = icon('calendar', { size: '1em', class: 'd-select-arrow' });
+  const trigger = buttonTag({
+    type: 'button',
+    class: 'd-select',
+    'aria-haspopup': 'dialog',
+    'aria-expanded': 'false'
+  }, displayEl, arrow);
+
+  const panel = div({ class: 'd-datetimepicker-panel' });
+  const wrap = div({ class: cx('d-datetimepicker', cls) }, trigger, panel);
+
+  function updateDisplay() {
+    displayEl.textContent = selected ? formatDisplay(selected) : placeholder;
+    if (!selected) displayEl.classList.add('d-select-placeholder');
+    else displayEl.classList.remove('d-select-placeholder');
+  }
+
+  // ─── Calendar rendering ───────────────────────────────
+  function renderPanel() {
+    panel.replaceChildren();
+    const year = viewDate.getFullYear();
+    const month = viewDate.getMonth();
+
+    // Calendar section
+    const calSection = div({ class: 'd-datetimepicker-date' });
+
+    // Nav header
+    const prevBtn = buttonTag({ type: 'button', class: 'd-datepicker-nav-btn', 'aria-label': 'Previous month' }, caret('left'));
+    const nextBtn = buttonTag({ type: 'button', class: 'd-datepicker-nav-btn', 'aria-label': 'Next month' }, caret('right'));
+    const titleEl = span({ class: 'd-datepicker-title' }, `${MONTHS[month]} ${year}`);
+
+    prevBtn.addEventListener('click', () => { viewDate.setMonth(month - 1); renderPanel(); });
+    nextBtn.addEventListener('click', () => { viewDate.setMonth(month + 1); renderPanel(); });
+
+    calSection.appendChild(div({ class: 'd-datepicker-header' },
+      div({ class: 'd-datepicker-nav' }, prevBtn), titleEl, div({ class: 'd-datepicker-nav' }, nextBtn)));
+
+    // Weekday headers
+    const grid = div({ class: 'd-datepicker-grid', role: 'grid' });
+    DAYS_HDR.forEach(d => grid.appendChild(div({ class: 'd-datepicker-weekday' }, d)));
+
+    // Days
+    const firstDay = new Date(year, month, 1).getDay();
+    const daysInMonth = new Date(year, month + 1, 0).getDate();
+    const daysInPrev = new Date(year, month, 0).getDate();
+    const today = new Date();
+
+    function sameDay(a, b) {
+      return a && b && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+    }
+
+    for (let i = firstDay - 1; i >= 0; i--) {
+      grid.appendChild(buttonTag({ type: 'button', class: 'd-datepicker-day d-datepicker-day-outside', tabindex: '-1' }, String(daysInPrev - i)));
+    }
+
+    for (let i = 1; i <= daysInMonth; i++) {
+      const d = new Date(year, month, i);
+      const dayClass = cx(
+        'd-datepicker-day',
+        sameDay(d, today) && 'd-datepicker-day-today',
+        sameDay(d, selected) && 'd-datepicker-day-selected',
+      );
+      const btn = buttonTag({ type: 'button', class: dayClass, tabindex: '-1' }, String(i));
+      btn.addEventListener('click', () => {
+        viewDate = new Date(d);
+        selected = buildDateTime(d, _h, _m, _s);
+        updateDisplay();
+        renderPanel();
+        if (onchange) onchange(new Date(selected));
+      });
+      grid.appendChild(btn);
+    }
+
+    const totalCells = firstDay + daysInMonth;
+    const remaining = (7 - (totalCells % 7)) % 7;
+    for (let i = 1; i <= remaining; i++) {
+      grid.appendChild(buttonTag({ type: 'button', class: 'd-datepicker-day d-datepicker-day-outside', tabindex: '-1' }, String(i)));
+    }
+
+    calSection.appendChild(grid);
+    panel.appendChild(calSection);
+
+    // ─── Time section ─────────────────────────────────
+    const timeSection = div({ class: 'd-datetimepicker-time' });
+    const timeLabel = div({ class: 'd-datetimepicker-time-label' }, 'Time');
+    timeSection.appendChild(timeLabel);
+
+    const timeRow = div({ class: 'd-datetimepicker-time-row' });
+
+    function createSpinner(val, minV, maxV, onChange) {
+      const inp = input({
+        type: 'number',
+        class: 'd-datetimepicker-spinner',
+        min: String(minV),
+        max: String(maxV),
+        value: String(val).padStart(2, '0'),
+      });
+      inp.addEventListener('change', () => {
+        let v = parseInt(inp.value, 10);
+        if (isNaN(v)) v = minV;
+        v = Math.max(minV, Math.min(maxV, v));
+        inp.value = String(v).padStart(2, '0');
+        onChange(v);
+      });
+      return inp;
+    }
+
+    const hInput = createSpinner(use12h ? (_h % 12 || 12) : _h, use12h ? 1 : 0, use12h ? 12 : 23, (v) => {
+      _h = use12h ? (v % 12) + (_h >= 12 ? 12 : 0) : v;
+      if (selected) { selected = buildDateTime(selected, _h, _m, _s); updateDisplay(); if (onchange) onchange(new Date(selected)); }
+    });
+
+    timeRow.appendChild(hInput);
+    timeRow.appendChild(span({ class: 'd-datetimepicker-sep' }, ':'));
+
+    const mInput = createSpinner(_m, 0, 59, (v) => {
+      _m = v;
+      if (selected) { selected = buildDateTime(selected, _h, _m, _s); updateDisplay(); if (onchange) onchange(new Date(selected)); }
+    });
+    timeRow.appendChild(mInput);
+
+    if (seconds) {
+      timeRow.appendChild(span({ class: 'd-datetimepicker-sep' }, ':'));
+      const sInput = createSpinner(_s, 0, 59, (v) => {
+        _s = v;
+        if (selected) { selected = buildDateTime(selected, _h, _m, _s); updateDisplay(); if (onchange) onchange(new Date(selected)); }
+      });
+      timeRow.appendChild(sInput);
+    }
+
+    if (use12h) {
+      const ampm = buttonTag({ type: 'button', class: 'd-datetimepicker-ampm' }, _h >= 12 ? 'PM' : 'AM');
+      ampm.addEventListener('click', () => {
+        _h = _h >= 12 ? _h - 12 : _h + 12;
+        ampm.textContent = _h >= 12 ? 'PM' : 'AM';
+        if (selected) { selected = buildDateTime(selected, _h, _m, _s); updateDisplay(); if (onchange) onchange(new Date(selected)); }
+      });
+      timeRow.appendChild(ampm);
+    }
+
+    timeSection.appendChild(timeRow);
+
+    // Now button
+    const nowBtn = buttonTag({ type: 'button', class: 'd-datetimepicker-now' }, 'Now');
+    nowBtn.addEventListener('click', () => {
+      const now = new Date();
+      selected = now;
+      viewDate = new Date(now);
+      _h = now.getHours(); _m = now.getMinutes(); _s = now.getSeconds();
+      updateDisplay();
+      renderPanel();
+      if (onchange) onchange(new Date(selected));
+    });
+    timeSection.appendChild(nowBtn);
+
+    panel.appendChild(timeSection);
+
+    // OK / Close button
+    const footer = div({ class: 'd-datetimepicker-footer' });
+    const okBtn = buttonTag({ type: 'button', class: 'd-btn d-btn-sm' }, 'OK');
+    okBtn.addEventListener('click', () => overlay.close());
+    footer.appendChild(okBtn);
+    panel.appendChild(footer);
+  }
+
+  const overlay = createOverlay(trigger, panel, {
+    trigger: 'click',
+    closeOnEscape: true,
+    closeOnOutside: true,
+    onOpen: renderPanel,
+  });
+
+  updateDisplay();
+
+  if (typeof value === 'function') {
+    createEffect(() => {
+      selected = parseVal(value());
+      if (selected) {
+        viewDate = new Date(selected);
+        _h = selected.getHours(); _m = selected.getMinutes(); _s = selected.getSeconds();
+      }
+      updateDisplay();
+    });
+  }
+
+  if (typeof disabled === 'function') {
+    createEffect(() => { trigger.disabled = !!disabled(); });
+  } else if (disabled) {
+    trigger.disabled = true;
+  }
+
+  onDestroy(() => {
+    overlay.destroy();
+  });
+
+  return wrap;
+}

package/src/components/descriptions.js

@@ -0,0 +1,68 @@
+/**
+ * Descriptions — Key-value pair display, like a detail panel.
+ *
+ * @module decantr/components/descriptions
+ */
+import { h } from '../core/index.js';
+import { injectBase, cx } from './_base.js';
+
+/**
+ * @param {Object} [props]
+ * @param {string} [props.title]
+ * @param {{ label: string, value: string|Node, span?: number }[]} [props.items]
+ * @param {number} [props.columns=3]
+ * @param {'horizontal'|'vertical'} [props.layout='horizontal']
+ * @param {boolean} [props.bordered=false]
+ * @param {string} [props.class]
+ * @returns {HTMLElement}
+ */
+export function Descriptions(props = {}) {
+  injectBase();
+  const { title, items = [], columns = 3, layout = 'horizontal', bordered, class: cls } = props;
+
+  const container = h('div', {
+    class: cx('d-descriptions', layout === 'horizontal' && 'd-descriptions-horizontal', cls)
+  });
+
+  if (title) {
+    container.appendChild(h('div', { class: 'd-descriptions-title' }, title));
+  }
+
+  const table = h('table', { class: 'd-descriptions-table' });
+  const tbody = h('tbody', null);
+
+  if (layout === 'horizontal') {
+    // Group items into rows based on column count
+    let currentRow = null;
+    let currentSpan = 0;
+
+    items.forEach(item => {
+      const span = item.span || 1;
+      if (!currentRow || currentSpan + span > columns) {
+        currentRow = h('tr', null);
+        tbody.appendChild(currentRow);
+        currentSpan = 0;
+      }
+      currentRow.appendChild(h('td', { class: 'd-descriptions-label' }, item.label));
+      const contentEl = h('td', { class: 'd-descriptions-content', colspan: span > 1 ? String(span * 2 - 1) : undefined });
+      if (typeof item.value === 'object' && item.value?.nodeType) contentEl.appendChild(item.value);
+      else contentEl.textContent = String(item.value ?? '');
+      currentRow.appendChild(contentEl);
+      currentSpan += span;
+    });
+  } else {
+    // Vertical: each item is its own row
+    items.forEach(item => {
+      const labelRow = h('tr', null, h('td', { class: 'd-descriptions-label', colspan: '2' }, item.label));
+      tbody.appendChild(labelRow);
+      const contentEl = h('td', { class: 'd-descriptions-content', colspan: '2' });
+      if (typeof item.value === 'object' && item.value?.nodeType) contentEl.appendChild(item.value);
+      else contentEl.textContent = String(item.value ?? '');
+      tbody.appendChild(h('tr', null, contentEl));
+    });
+  }
+
+  table.appendChild(tbody);
+  container.appendChild(table);
+  return container;
+}

package/src/components/drawer.js

@@ -0,0 +1,179 @@
+/**
+ * Drawer — Slide-over panel from any edge of the screen.
+ * Uses native <dialog> with focus trap. Supports compound sub-components.
+ *
+ * @module decantr/components/drawer
+ */
+import { onDestroy } from '../core/index.js';
+import { createEffect } from '../state/index.js';
+import { tags } from '../tags/index.js';
+import { injectBase, cx } from './_base.js';
+import { createFocusTrap } from './_behaviors.js';
+import { icon } from './icon.js';
+
+const { div, button, span, dialog: dialogTag } = tags;
+
+const DRAWER_SECTIONS = ['d-drawer-header', 'd-drawer-body', 'd-drawer-footer'];
+
+function hasSection(children) {
+  return children.some(c =>
+    c && typeof c === 'object' && c.nodeType === 1 &&
+    (c.className || '').split(/\s+/).some(cls => DRAWER_SECTIONS.includes(cls))
+  );
+}
+
+/**
+ * @param {Object} [props]
+ * @param {Function} props.visible — Signal getter returning boolean
+ * @param {Function} [props.onClose]
+ * @param {'left'|'right'|'top'|'bottom'} [props.side='right']
+ * @param {string} [props.title]
+ * @param {Node|Node[]} [props.footer] — Footer content (wrapped in d-drawer-footer)
+ * @param {string} [props.size] — CSS width/height (default: '320px')
+ * @param {boolean} [props.closeOnOutside=true]
+ * @param {string} [props.width] — Deprecated: use size
+ * @param {string} [props.height] — Deprecated: use size
+ * @param {string} [props.class]
+ * @param {...Node} children
+ * @returns {HTMLDialogElement}
+ */
+export function Drawer(props = {}, ...children) {
+  injectBase();
+
+  const {
+    visible,
+    onClose,
+    side = 'right',
+    title,
+    footer,
+    size,
+    closeOnOutside = true,
+    width,
+    height,
+    class: cls
+  } = props;
+
+  const isHorizontal = side === 'left' || side === 'right';
+  const effectiveSize = size || (isHorizontal ? width : height) || '320px';
+
+  const closeBtn = button({
+    class: 'd-drawer-close',
+    type: 'button',
+    'aria-label': 'Close drawer'
+  }, icon('x', { size: '1em' }));
+
+  const panel = div({
+    class: cx('d-drawer-panel', `d-drawer-${side}`)
+  });
+
+  // Set size — runtime value from user prop
+  if (isHorizontal) {
+    panel.style.width = effectiveSize;
+  } else {
+    panel.style.height = effectiveSize;
+  }
+
+  if (hasSection(children)) {
+    // Explicit sections — pass through directly
+    children.forEach(c => { if (c) panel.appendChild(c); });
+  } else {
+    // Auto-wrap: title → header, children → body, footer → footer
+    const headerChildren = [];
+    if (title) headerChildren.push(span({ class: 'd-drawer-title' }, title));
+    headerChildren.push(closeBtn);
+    panel.appendChild(div({ class: 'd-drawer-header' }, ...headerChildren));
+
+    if (children.length) {
+      panel.appendChild(div({ class: 'd-drawer-body' }, ...children));
+    }
+    if (footer) {
+      const footerChildren = Array.isArray(footer) ? footer : [footer];
+      panel.appendChild(div({ class: 'd-drawer-footer' }, ...footerChildren));
+    }
+  }
+
+  const dialog = dialogTag({
+    class: cx('d-drawer', cls),
+    role: 'dialog',
+    'aria-modal': 'true',
+    'aria-label': title || 'Drawer'
+  }, panel);
+
+  const trap = createFocusTrap(dialog);
+
+  function close() {
+    if (dialog.open) dialog.close();
+  }
+
+  // Close button calls close() only — onClose fires from dialog 'close' event
+  closeBtn.addEventListener('click', close);
+
+  dialog.addEventListener('close', () => {
+    trap.deactivate();
+    if (onClose) onClose();
+  });
+
+  // Click on backdrop (outside panel rect) closes
+  if (closeOnOutside) {
+    dialog.addEventListener('click', (e) => {
+      const rect = panel.getBoundingClientRect();
+      if (e.clientX < rect.left || e.clientX > rect.right ||
+          e.clientY < rect.top || e.clientY > rect.bottom) {
+        close();
+      }
+    });
+  }
+
+  dialog.addEventListener('cancel', () => {
+    if (onClose) onClose();
+  });
+
+  if (typeof visible === 'function') {
+    createEffect(() => {
+      if (visible()) {
+        if (!dialog.open) { dialog.showModal(); trap.activate(); }
+      } else {
+        close();
+      }
+    });
+  }
+
+  onDestroy(() => {
+    trap.deactivate();
+  });
+
+  return dialog;
+}
+
+/**
+ * Drawer.Header — drawer header section
+ * @param {Object} [props]
+ * @param {...(string|Node)} children
+ * @returns {HTMLElement}
+ */
+Drawer.Header = function DrawerHeader(props = {}, ...children) {
+  const { class: cls } = props;
+  return div({ class: cx('d-drawer-header', cls) }, ...children);
+};
+
+/**
+ * Drawer.Body — drawer body section
+ * @param {Object} [props]
+ * @param {...(string|Node)} children
+ * @returns {HTMLElement}
+ */
+Drawer.Body = function DrawerBody(props = {}, ...children) {
+  const { class: cls } = props;
+  return div({ class: cx('d-drawer-body', cls) }, ...children);
+};
+
+/**
+ * Drawer.Footer — drawer footer section
+ * @param {Object} [props]
+ * @param {...(string|Node)} children
+ * @returns {HTMLElement}
+ */
+Drawer.Footer = function DrawerFooter(props = {}, ...children) {
+  const { class: cls } = props;
+  return div({ class: cx('d-drawer-footer', cls) }, ...children);
+};

package/src/components/dropdown.js

@@ -0,0 +1,88 @@
+/**
+ * Dropdown — Menu triggered by a button.
+ * Uses renderMenuItems primitive + createListbox + createOverlay behaviors.
+ *
+ * @module decantr/components/dropdown
+ */
+import { onDestroy } from '../core/index.js';
+import { tags } from '../tags/index.js';
+import { injectBase, cx } from './_base.js';
+import { createListbox, createOverlay } from './_behaviors.js';
+import { renderMenuItems } from './_primitives.js';
+
+const { div, button: buttonTag } = tags;
+
+/**
+ * @param {Object} [props]
+ * @param {Function} [props.trigger] — Function returning trigger element
+ * @param {{ label: string, value?: string, icon?: string|Node, shortcut?: string, disabled?: boolean, separator?: boolean, onclick?: Function }[]} [props.items]
+ * @param {string} [props.align] — 'left'|'right' (default: 'left')
+ * @param {string} [props.class]
+ * @returns {HTMLElement}
+ */
+export function Dropdown(props = {}) {
+  injectBase();
+
+  const { trigger, items = [], align = 'left', class: cls } = props;
+
+  const menu = div({
+    class: cx('d-dropdown-menu', align === 'right' && 'd-dropdown-right'),
+    role: 'menu',
+    tabindex: '-1'
+  });
+
+  const wrap = div({ class: cx('d-dropdown', cls) });
+
+  const triggerEl = typeof trigger === 'function' ? trigger() : buttonTag({ type: 'button', class: 'd-dropdown-trigger' }, 'Menu');
+  triggerEl.setAttribute('aria-haspopup', 'menu');
+  triggerEl.setAttribute('aria-expanded', 'false');
+  wrap.appendChild(triggerEl);
+  wrap.appendChild(menu);
+
+  // Overlay handles show/hide, click-outside, escape, ARIA expanded
+  const overlay = createOverlay(triggerEl, menu, {
+    trigger: 'click',
+    closeOnEscape: true,
+    closeOnOutside: true,
+    onOpen() {
+      renderMenuItems(menu, items, { onClose: closeMenu });
+      listbox.reset();
+      wrap.classList.add('d-dropdown-open');
+      if (typeof menu.focus === 'function') menu.focus();
+    },
+    onClose() {
+      wrap.classList.remove('d-dropdown-open');
+      if (typeof triggerEl.focus === 'function') triggerEl.focus();
+    }
+  });
+
+  function closeMenu() {
+    overlay.close();
+  }
+
+  // Listbox handles arrow keys, enter/space selection, home/end
+  const listbox = createListbox(menu, {
+    itemSelector: '.d-dropdown-item:not(.d-dropdown-item-disabled)',
+    activeClass: 'd-dropdown-item-highlight',
+    orientation: 'vertical',
+    onSelect: (el) => el.click()
+  });
+
+  // ArrowDown on trigger opens menu and highlights first item
+  triggerEl.addEventListener('keydown', (e) => {
+    if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      if (!overlay.isOpen()) {
+        overlay.open();
+      }
+      listbox.highlight(0);
+    }
+  });
+
+  onDestroy(() => {
+    overlay.destroy();
+    listbox.destroy();
+  });
+
+  return wrap;
+}

package/src/components/empty.js

@@ -0,0 +1,41 @@
+/**
+ * Empty — Placeholder for empty states (no data, no results, etc.).
+ *
+ * @module decantr/components/empty
+ */
+import { h } from '../core/index.js';
+import { injectBase, cx } from './_base.js';
+
+/**
+ * @param {Object} [props]
+ * @param {string|Node} [props.icon] - Custom icon (default: generic empty icon)
+ * @param {string} [props.description='No data']
+ * @param {string} [props.class]
+ * @param {...Node} children - Optional action buttons below description
+ * @returns {HTMLElement}
+ */
+export function Empty(props = {}, ...children) {
+  injectBase();
+  const { icon, description = 'No data', class: cls, ...rest } = props;
+
+  const container = h('div', { class: cx('d-empty', cls), ...rest });
+
+  const iconEl = h('div', { class: 'd-empty-icon' });
+  if (icon) {
+    if (typeof icon === 'string') iconEl.textContent = icon;
+    else iconEl.appendChild(icon);
+  } else {
+    iconEl.textContent = '\uD83D\uDDC3';
+  }
+  container.appendChild(iconEl);
+
+  if (description) {
+    container.appendChild(h('div', { class: 'd-empty-desc' }, description));
+  }
+
+  children.forEach(child => {
+    if (child && child.nodeType) container.appendChild(child);
+  });
+
+  return container;
+}