decantr 0.9.0

package/src/components/carousel.js

@@ -0,0 +1,98 @@
+/**
+ * Carousel — Slide-based content carousel with navigation and dots.
+ *
+ * @module decantr/components/carousel
+ */
+import { h } from '../core/index.js';
+import { injectBase, cx } from './_base.js';
+import { caret } from './_behaviors.js';
+
+/**
+ * @param {Object} [props]
+ * @param {Node[]} [props.slides] - Array of slide elements
+ * @param {boolean} [props.autoplay=false]
+ * @param {number} [props.interval=3000] - Autoplay interval in ms
+ * @param {boolean} [props.arrows=true] - Show prev/next arrows
+ * @param {boolean} [props.dots=true] - Show dot indicators
+ * @param {boolean} [props.loop=true] - Loop around edges
+ * @param {Function} [props.onChange] - Called with current index
+ * @param {string} [props.class]
+ * @returns {HTMLElement}
+ */
+export function Carousel(props = {}) {
+  injectBase();
+  const { slides = [], autoplay = false, interval = 3000, arrows = true, dots = true, loop = true, onChange, class: cls } = props;
+
+  let current = 0;
+  let _timer = null;
+
+  const track = h('div', { class: 'd-carousel-track' });
+  slides.forEach(slide => {
+    const slideEl = h('div', { class: 'd-carousel-slide' });
+    slideEl.appendChild(slide);
+    track.appendChild(slideEl);
+  });
+
+  const container = h('div', { class: cx('d-carousel', cls) }, track);
+
+  function goTo(idx) {
+    if (!loop) idx = Math.max(0, Math.min(idx, slides.length - 1));
+    else idx = (idx + slides.length) % slides.length;
+    current = idx;
+    track.style.transform = `translateX(-${current * 100}%)`;
+    updateDots();
+    if (onChange) onChange(current);
+  }
+
+  function next() { goTo(current + 1); }
+  function prev() { goTo(current - 1); }
+
+  // Arrows
+  if (arrows && slides.length > 1) {
+    const prevBtn = h('button', { type: 'button', class: 'd-carousel-nav d-carousel-prev', 'aria-label': 'Previous slide' }, caret('left'));
+    const nextBtn = h('button', { type: 'button', class: 'd-carousel-nav d-carousel-next', 'aria-label': 'Next slide' }, caret('right'));
+    prevBtn.addEventListener('click', prev);
+    nextBtn.addEventListener('click', next);
+    container.appendChild(prevBtn);
+    container.appendChild(nextBtn);
+  }
+
+  // Dots
+  let dotEls = [];
+  function updateDots() {
+    dotEls.forEach((d, i) => d.classList.toggle('d-carousel-dot-active', i === current));
+  }
+
+  if (dots && slides.length > 1) {
+    const dotsContainer = h('div', { class: 'd-carousel-dots' });
+    slides.forEach((_, i) => {
+      const dot = h('button', {
+        type: 'button',
+        class: cx('d-carousel-dot', i === 0 && 'd-carousel-dot-active'),
+        'aria-label': `Slide ${i + 1}`
+      });
+      dot.addEventListener('click', () => goTo(i));
+      dotEls.push(dot);
+      dotsContainer.appendChild(dot);
+    });
+    container.appendChild(dotsContainer);
+  }
+
+  // Autoplay
+  if (autoplay && slides.length > 1) {
+    function startTimer() { _timer = setInterval(next, interval); }
+    function stopTimer() { clearInterval(_timer); }
+    startTimer();
+    container.addEventListener('mouseenter', stopTimer);
+    container.addEventListener('mouseleave', startTimer);
+  }
+
+  // Keyboard
+  container.setAttribute('tabindex', '0');
+  container.addEventListener('keydown', (e) => {
+    if (e.key === 'ArrowLeft') { e.preventDefault(); prev(); }
+    else if (e.key === 'ArrowRight') { e.preventDefault(); next(); }
+  });
+
+  return container;
+}

package/src/components/cascader.js

@@ -0,0 +1,261 @@
+/**
+ * Cascader — Multi-level selection dropdown.
+ * Each column shows children of the selected parent.
+ * Uses createFieldOverlay + createListbox.
+ *
+ * @module decantr/components/cascader
+ */
+import { onDestroy } from '../core/index.js';
+import { createSignal, createEffect } from '../state/index.js';
+import { tags } from '../tags/index.js';
+import { injectBase, cx } from './_base.js';
+import { caret, createFormField } from './_behaviors.js';
+import { applyFieldState, createFieldOverlay } from './_primitives.js';
+
+const { div, input: inputTag, button: buttonTag, span } = tags;
+
+/**
+ * @typedef {Object} CascaderOption
+ * @property {string} label
+ * @property {string} value
+ * @property {CascaderOption[]} [children]
+ * @property {boolean} [disabled]
+ */
+
+/**
+ * @param {Object} [props]
+ * @param {CascaderOption[]} [props.options]
+ * @param {string[]} [props.value]
+ * @param {Function} [props.onChange]
+ * @param {string} [props.placeholder='Select']
+ * @param {boolean|Function} [props.disabled]
+ * @param {boolean} [props.clearable=true]
+ * @param {string} [props.separator=' / ']
+ * @param {'click'|'hover'} [props.expandTrigger='click']
+ * @param {boolean} [props.searchable=false]
+ * @param {boolean|string|Function} [props.error]
+ * @param {boolean|string|Function} [props.success]
+ * @param {string} [props.variant='outlined'] - 'outlined'|'filled'|'ghost'
+ * @param {string} [props.size] - xs|sm|lg
+ * @param {string} [props.label]
+ * @param {string} [props.help]
+ * @param {boolean} [props.required]
+ * @param {string} [props.class]
+ * @returns {HTMLElement}
+ */
+export function Cascader(props = {}) {
+  injectBase();
+  const {
+    options = [], value, onChange, placeholder = 'Select', disabled = false,
+    clearable = true, separator = ' / ', expandTrigger = 'click',
+    searchable = false, error, success, variant, size,
+    label, help, required, class: cls
+  } = props;
+
+  const [selectedPath, setSelectedPath] = createSignal(value || []);
+  const [columns, setColumns] = createSignal([options]);
+
+  const clearBtn = span({ class: 'd-cascader-clear', role: 'button', 'aria-label': 'Clear', tabindex: '-1' }, '\u00d7');
+  clearBtn.style.display = 'none';
+
+  // Both modes use a div trigger with role=combobox + tabindex.
+  // Non-searchable: display span + caret (select-like affordance, no fake <input readonly>).
+  // Searchable: real <input> for typing.
+  let trigger, displayEl, setDisplayText;
+
+  if (searchable) {
+    displayEl = inputTag({
+      type: 'text',
+      class: 'd-cascader-input',
+      placeholder
+    });
+    setDisplayText = (t) => { displayEl.value = t; };
+    trigger = div({
+      class: 'd-cascader-trigger',
+      role: 'combobox',
+      'aria-expanded': 'false',
+      'aria-haspopup': 'listbox',
+      tabindex: disabled ? undefined : '0'
+    }, displayEl, clearBtn);
+  } else {
+    const displaySpan = span({ class: 'd-cascader-display' });
+    const placeholderSpan = span({ class: 'd-cascader-placeholder' }, placeholder);
+    displayEl = displaySpan;
+    setDisplayText = (t) => {
+      displaySpan.textContent = t;
+      placeholderSpan.style.display = t ? 'none' : '';
+      displaySpan.style.display = t ? '' : 'none';
+    };
+    trigger = div({
+      class: 'd-cascader-trigger',
+      role: 'combobox',
+      'aria-expanded': 'false',
+      'aria-haspopup': 'listbox',
+      tabindex: disabled ? undefined : '0'
+    }, placeholderSpan, displaySpan, clearBtn, caret('down'));
+  }
+
+  const dropdown = div({ class: 'd-cascader-dropdown' });
+
+  const wrap = div({ class: cx('d-cascader', cls) }, trigger, dropdown);
+
+  applyFieldState(wrap, { error, success, disabled, variant, size });
+
+  const overlay = createFieldOverlay(trigger, dropdown, {
+    trigger: disabled ? 'manual' : 'click',
+    matchWidth: false,
+    onOpen: () => {
+      wrap.classList.add('d-cascader-open');
+      trigger.setAttribute('aria-expanded', 'true');
+    },
+    onClose: () => {
+      wrap.classList.remove('d-cascader-open');
+      trigger.setAttribute('aria-expanded', 'false');
+      if (searchable) setDisplayText(getDisplayText());
+    }
+  });
+
+  function getDisplayText() {
+    const path = selectedPath();
+    if (!path.length) return '';
+    const labels = [];
+    let current = options;
+    for (const val of path) {
+      const opt = current.find(o => o.value === val);
+      if (!opt) break;
+      labels.push(opt.label);
+      current = opt.children || [];
+    }
+    return labels.join(separator);
+  }
+
+  function renderColumns() {
+    const cols = columns();
+    dropdown.replaceChildren();
+
+    cols.forEach((colOptions, colIdx) => {
+      const colEl = div({ class: 'd-cascader-column', role: 'listbox' });
+
+      colOptions.forEach(opt => {
+        const isSelected = selectedPath()[colIdx] === opt.value;
+        const hasChildren = opt.children && opt.children.length > 0;
+
+        const itemEl = div({
+          class: cx('d-cascader-option', isSelected && 'd-cascader-option-active', opt.disabled && 'd-cascader-option-disabled'),
+          role: 'option',
+          'aria-selected': isSelected ? 'true' : 'false',
+          tabindex: '-1'
+        },
+          span({ class: 'd-cascader-option-label' }, opt.label),
+          hasChildren ? caret('right', { class: 'd-cascader-option-arrow' }) : null
+        );
+
+        if (!opt.disabled) {
+          const selectItem = () => {
+            const newPath = selectedPath().slice(0, colIdx);
+            newPath[colIdx] = opt.value;
+
+            if (hasChildren) {
+              const newCols = cols.slice(0, colIdx + 1);
+              newCols.push(opt.children);
+              setColumns(newCols);
+              setSelectedPath(newPath);
+            } else {
+              setSelectedPath(newPath);
+              setColumns([options]);
+              setDisplayText(getDisplayText());
+              overlay.close();
+              if (onChange) {
+                const selectedOpts = [];
+                let cur = options;
+                for (const v of newPath) {
+                  const o = cur.find(x => x.value === v);
+                  if (o) { selectedOpts.push(o); cur = o.children || []; }
+                }
+                onChange(newPath, selectedOpts);
+              }
+            }
+            renderColumns();
+          };
+
+          if (expandTrigger === 'hover' && hasChildren) {
+            itemEl.addEventListener('mouseenter', selectItem);
+          }
+          itemEl.addEventListener('click', selectItem);
+        }
+
+        colEl.appendChild(itemEl);
+      });
+
+      dropdown.appendChild(colEl);
+    });
+  }
+
+  // Clear
+  if (clearable) {
+    clearBtn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      setSelectedPath([]);
+      setColumns([options]);
+      setDisplayText('');
+      clearBtn.style.display = 'none';
+      if (onChange) onChange([], []);
+    });
+  }
+
+  // Search filtering (only available in searchable mode with input trigger)
+  if (searchable) {
+    displayEl.addEventListener('input', () => {
+      const q = displayEl.value.toLowerCase();
+      if (!q) { setColumns([options]); renderColumns(); return; }
+
+      const flat = [];
+      function walk(opts, path, labels) {
+        opts.forEach(o => {
+          const newPath = [...path, o.value];
+          const newLabels = [...labels, o.label];
+          if (o.children && o.children.length) walk(o.children, newPath, newLabels);
+          else flat.push({ label: newLabels.join(separator), value: newPath, option: o });
+        });
+      }
+      walk(options, [], []);
+
+      const filtered = flat.filter(f => f.label.toLowerCase().includes(q));
+      const searchCol = filtered.map(f => ({
+        label: f.label, value: f.value.join(','), children: null, _path: f.value
+      }));
+
+      setColumns([searchCol]);
+      renderColumns();
+    });
+  }
+
+  // Sync display
+  createEffect(() => {
+    const path = selectedPath();
+    setDisplayText(getDisplayText());
+    clearBtn.style.display = (clearable && path.length) ? '' : 'none';
+  });
+
+  createEffect(() => { renderColumns(); });
+
+  onDestroy(() => { overlay.destroy(); });
+
+  // Reactive disabled
+  if (typeof disabled === 'function') {
+    createEffect(() => {
+      const v = disabled();
+      trigger.setAttribute('tabindex', v ? '' : '0');
+      if (searchable) displayEl.disabled = v;
+    });
+  } else if (disabled && searchable) {
+    displayEl.disabled = true;
+  }
+
+  if (label || help) {
+    const { wrapper } = createFormField(wrap, { label, error, help, required, success, variant, size });
+    return wrapper;
+  }
+
+  return wrap;
+}

package/src/components/checkbox.js

@@ -0,0 +1,80 @@
+import { createEffect } from '../state/index.js';
+import { tags } from '../tags/index.js';
+import { injectBase, cx } from './_base.js';
+import { createFormField } from './_behaviors.js';
+
+const { label: labelTag, input: inputTag, span } = tags;
+
+/**
+ * @param {Object} [props]
+ * @param {boolean|Function} [props.checked]
+ * @param {boolean|Function} [props.disabled]
+ * @param {string} [props.label]
+ * @param {boolean} [props.indeterminate]
+ * @param {boolean|string|Function} [props.error]
+ * @param {boolean|string|Function} [props.success]
+ * @param {string} [props.help] - Help text for createFormField
+ * @param {boolean} [props.required]
+ * @param {string} [props.size] - xs|sm|lg
+ * @param {Function} [props.onchange]
+ * @param {string} [props['aria-label']]
+ * @param {string} [props.class]
+ * @returns {HTMLElement}
+ */
+export function Checkbox(props = {}) {
+  injectBase();
+
+  const { checked, disabled, label, indeterminate, error, success, help, required, size, onchange, 'aria-label': ariaLabel, class: cls } = props;
+
+  const inputProps = { type: 'checkbox', class: 'd-checkbox-native' };
+  if (ariaLabel) inputProps['aria-label'] = ariaLabel;
+
+  const input = inputTag(inputProps);
+  const check = span({ class: 'd-checkbox-check' });
+  const wrapper = labelTag({ class: cx('d-checkbox', size && `d-checkbox-${size}`, cls) }, input, check);
+
+  if (label) wrapper.appendChild(span({ class: 'd-checkbox-label' }, label));
+  if (indeterminate) input.indeterminate = true;
+  if (onchange) input.addEventListener('change', () => onchange(input.checked));
+  if (required) input.required = true;
+
+  if (typeof checked === 'function') {
+    createEffect(() => { input.checked = checked(); });
+  } else if (checked) {
+    input.checked = true;
+  }
+
+  // Reactive disabled
+  if (typeof disabled === 'function') {
+    createEffect(() => { input.disabled = disabled(); });
+  } else if (disabled) {
+    input.disabled = true;
+  }
+
+  // Reactive error — mark wrapper with data-error
+  if (typeof error === 'function') {
+    createEffect(() => {
+      const v = error();
+      wrapper.toggleAttribute('data-error', !!v);
+      input.setAttribute('aria-invalid', v ? 'true' : 'false');
+    });
+  } else if (error) {
+    wrapper.setAttribute('data-error', '');
+    input.setAttribute('aria-invalid', 'true');
+  }
+
+  // Reactive success
+  if (typeof success === 'function') {
+    createEffect(() => { wrapper.toggleAttribute('data-success', !!success()); });
+  } else if (success) {
+    wrapper.setAttribute('data-success', '');
+  }
+
+  // Form field wrapping (when help is provided)
+  if (help) {
+    const { wrapper: formWrapper } = createFormField(wrapper, { label, error, help, required, success });
+    return formWrapper;
+  }
+
+  return wrapper;
+}

package/src/components/chip.js

@@ -0,0 +1,81 @@
+import { h } from '../core/index.js';
+import { injectBase, cx } from './_base.js';
+import { icon as iconHelper } from './icon.js';
+
+/**
+ * @param {Object} [props]
+ * @param {string|Node} [props.icon] - Leading icon (string = icon name, Node = element)
+ * @param {string} props.label - Text content
+ * @param {string} [props.variant] - default|outline|filled (default: 'default')
+ * @param {string} [props.size] - xs|sm|lg
+ * @param {boolean} [props.removable] - Show dismiss X button
+ * @param {Function} [props.onRemove] - Dismiss callback
+ * @param {Function} [props.onClick] - Click handler (makes chip interactive)
+ * @param {boolean} [props.selected] - Selected/active state
+ * @param {string} [props.class]
+ * @returns {HTMLElement}
+ */
+export function Chip(props = {}) {
+  injectBase();
+
+  const {
+    icon, label, variant, size, removable, onRemove, onClick,
+    selected, class: cls
+  } = props;
+
+  const className = cx(
+    'd-chip',
+    variant === 'outline' && 'd-chip-outline',
+    variant === 'filled' && 'd-chip-filled',
+    size && `d-chip-${size}`,
+    selected && 'd-chip-selected',
+    (onClick || removable) && 'd-chip-interactive',
+    cls
+  );
+
+  const el = h('span', {
+    class: className,
+    role: onClick ? 'button' : undefined,
+    tabindex: onClick ? '0' : undefined
+  });
+
+  if (onClick) {
+    el.addEventListener('click', onClick);
+    el.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault();
+        onClick(e);
+      }
+    });
+  }
+
+  if (icon) {
+    const iconEl = typeof icon === 'string'
+      ? iconHelper(icon, { size: '1em', class: 'd-chip-icon' })
+      : icon;
+    if (iconEl && !iconEl.classList.contains('d-chip-icon')) {
+      iconEl.classList.add('d-chip-icon');
+    }
+    iconEl.setAttribute('aria-hidden', 'true');
+    el.appendChild(iconEl);
+  }
+
+  if (label) {
+    el.appendChild(h('span', { class: 'd-chip-label' }, label));
+  }
+
+  if (removable) {
+    const removeBtn = h('button', {
+      class: 'd-chip-remove',
+      type: 'button',
+      'aria-label': `Remove ${label || ''}`.trim(),
+      onclick: (e) => {
+        e.stopPropagation();
+        if (onRemove) onRemove(e);
+      }
+    }, iconHelper('x', { size: '1em' }));
+    el.appendChild(removeBtn);
+  }
+
+  return el;
+}

package/src/components/code-block.js

@@ -0,0 +1,82 @@
+/**
+ * CodeBlock — Structured code display with line numbers, copy button, and language label.
+ * No syntax highlighting (zero-dependency). Users can integrate Prism/Shiki externally.
+ *
+ * @module decantr/components/code-block
+ */
+import { h } from '../core/index.js';
+import { injectBase, cx } from './_base.js';
+
+/**
+ * @param {Object} [props]
+ * @param {string} [props.language] - Language label (e.g. 'javascript', 'html')
+ * @param {boolean} [props.lineNumbers=false] - Show line numbers
+ * @param {boolean} [props.copyable=true] - Show copy button
+ * @param {number} [props.maxHeight] - Max height in px (scroll if exceeded)
+ * @param {string} [props.class]
+ * @param {...string} children - Code string(s)
+ * @returns {HTMLElement}
+ */
+export function CodeBlock(props = {}, ...children) {
+  injectBase();
+
+  const { language, lineNumbers = false, copyable = true, maxHeight, class: cls } = props;
+  const code = children.join('');
+  const lines = code.split('\n');
+
+  const wrap = h('div', { class: cx('d-codeblock', cls) });
+
+  // Header bar (language label + copy button)
+  if (language || copyable) {
+    const header = h('div', { class: 'd-codeblock-header' });
+
+    if (language) {
+      header.appendChild(h('span', { class: 'd-codeblock-lang' }, language));
+    }
+
+    if (copyable) {
+      const copyBtn = h('button', {
+        type: 'button',
+        class: 'd-codeblock-copy',
+        'aria-label': 'Copy code'
+      }, 'Copy');
+      copyBtn.addEventListener('click', async () => {
+        try {
+          await navigator.clipboard.writeText(code);
+          copyBtn.textContent = 'Copied!';
+          setTimeout(() => { copyBtn.textContent = 'Copy'; }, 2000);
+        } catch (_) {
+          copyBtn.textContent = 'Failed';
+          setTimeout(() => { copyBtn.textContent = 'Copy'; }, 2000);
+        }
+      });
+      header.appendChild(copyBtn);
+    }
+
+    wrap.appendChild(header);
+  }
+
+  // Code area
+  const pre = h('pre', {
+    class: 'd-codeblock-pre',
+    style: maxHeight ? { maxHeight: `${maxHeight}px`, overflow: 'auto' } : undefined
+  });
+
+  if (lineNumbers) {
+    const gutter = h('span', { class: 'd-codeblock-gutter', 'aria-hidden': 'true' });
+    for (let i = 1; i <= lines.length; i++) {
+      gutter.appendChild(h('span', { class: 'd-codeblock-ln' }, String(i)));
+      if (i < lines.length) gutter.appendChild(document.createTextNode('\n'));
+    }
+    pre.appendChild(gutter);
+  }
+
+  const codeEl = h('code', {
+    class: cx('d-codeblock-code', language && `language-${language}`)
+  });
+  codeEl.textContent = code;
+  pre.appendChild(codeEl);
+
+  wrap.appendChild(pre);
+  return wrap;
+}

package/src/components/collapsible.js

@@ -0,0 +1,50 @@
+/**
+ * Collapsible — Simple expand/collapse container.
+ * Uses createDisclosure behavior for smooth animation.
+ *
+ * @module decantr/components/collapsible
+ */
+import { h } from '../core/index.js';
+import { createEffect } from '../state/index.js';
+import { injectBase, cx } from './_base.js';
+import { createDisclosure } from './_behaviors.js';
+
+/**
+ * @param {Object} [props]
+ * @param {boolean|Function} [props.open=false] - Open state
+ * @param {Function} [props.onToggle] - Called with new open state
+ * @param {string} [props.class]
+ * @param {Function} props.trigger - Function returning the trigger element
+ * @param {...Node} children - Collapsible content
+ * @returns {HTMLElement}
+ */
+export function Collapsible(props = {}, ...children) {
+  injectBase();
+  const { open = false, onToggle, trigger, class: cls, ...rest } = props;
+
+  const triggerEl = typeof trigger === 'function' ? trigger() : h('button', { type: 'button' }, 'Toggle');
+  const content = h('div', { class: 'd-collapsible-content' }, ...children);
+  const region = h('div', { class: 'd-disclosure-region' }, content);
+
+  const wrap = h('div', {
+    class: cx('d-collapsible', cls),
+    ...rest
+  }, triggerEl, region);
+
+  const defaultOpen = typeof open === 'function' ? open() : open;
+  const disclosure = createDisclosure(triggerEl, content, {
+    defaultOpen,
+    animate: true,
+    onToggle: (isOpen) => { if (onToggle) onToggle(isOpen); }
+  });
+
+  if (typeof open === 'function') {
+    createEffect(() => {
+      const v = open();
+      if (v && !disclosure.isOpen()) disclosure.open();
+      else if (!v && disclosure.isOpen()) disclosure.close();
+    });
+  }
+
+  return wrap;
+}