@txstate-mws/svelte-components 1.6.11 → 1.6.13

package/dist/components/PopupMenu.svelte

@@ -2,304 +2,299 @@
   The purpose of [`PopupMenu`](https://github.com/txstate-etc/svelte-components/blob/main/docs/PopupMenu.md) is to display a menu of options to the user, activated by clicking any element
   bound to `buttonelement`. It can also be controlled from the parent, by binding the `menushown` boolean.
 -->
-<script lang="ts">import { createEventDispatcher, onDestroy, tick } from 'svelte';
-import { groupby, isNull, randomid } from 'txstate-utils';
-import { Store } from '@txstate-mws/svelte-store';
-import { glue, portal } from '../actions';
-import ScreenReaderOnly from './ScreenReaderOnly.svelte';
-import { getScrollParents, modifierKey } from '../util';
-const dispatch = createEventDispatcher();
-/** The DOM element that will act as the "button" for this menu. The menu will be placed next to the
-button and be controlled by the button. Keyboard access will be enabled when the button has focus.
-This component adds all appropriate attributes (tabindex, roles, and aria) automatically. */
-export let buttonelement;
-/** The list of menu items to be shown. Parent may change this at any time based on user activity. */
-export let items = [];
-export let menushown = false;
-export let value = undefined;
-/** Control where the menu will appear. Default is to use the current viewport to make a decision to
-maximize potential for menu growth. */
-export let align = 'auto';
-/** When the menu is active, should it cover the button or be rendered above/below it? */
-export let cover = false;
-/** When an item is currently selected, should it appear in the menu (with a visual indicator), or
-simply be removed from the list (`showSelected: false`). */
-export let showSelected = true;
-/** When defined, this width will be passed through to the menu's CSS width. Use a valid CSS dimension
-such as 33em or 159px. Generally this will be used when you need to match the menu width to something
-else, like the button. If the width is static like 100% a simple CSS rule is likely more efficient. */
-export let width = undefined;
-/** Bind this prop to receive a store that is updated each time a menu placement decision is made. Example
-of when this is useful is when you are trying to round corners of your button and need to know whether the
-menu is above or below your button so you know which corners to round and which to leave square. Note that
-the values do not update when the menu is hidden, so you may need to rely on `menushown` as well. */
-export let computedalign = new Store({ valign: 'bottom', halign: 'left' });
-/** Create some spacing between the specified button element and the menu, in pixels */
-export let gap = 0;
-/** Set to `true` if you want the parent element's styling to increase its minHeight when necessary. Useful
-for parent elements not styled for variable size children and which you want override the the size of. */
-export let adjustparentheight = false;
-/**  If the menu would be clipped by an `overflow: hidden`, you can set this prop and it will be placed in
-the specified container, or the `document.body` if you simply say `true`. Placement will still be calculated
-correctly since it uses positon fixed for placement. */
-export let usePortal = undefined;
-/** Useful for when your `items` need to be fetched but you want the associated element shown. Set to loading
-until they're ready to be displayed and the popup menu will not be shown until the `loading` bind is `true`. */
-export let loading = false;
-/** A bindable value for inspecting which item in `items` is currently highlighted as the item currently
-active in the list. This is not the same as `value` and the highlighted item may or may not be selected as
-for the `value` of the field. */
-export let hilited = undefined;
-/** The id of the <ul> element that is the displayed list of items. */
-export let menuid = randomid();
-/** When there are no items (e.g. it's a filtered search and there were no results), we still display one
-disabled item in the menu to let the user know what is going on. Use this prop to specify the message. */
-export let emptyText = undefined;
-export let menuContainerClass = '';
-export let menuClass = '';
-export let menuItemClass = '';
-export let menuItemHilitedClass = '';
-export let menuItemSelectedClass = '';
-export let menuCategoryClass = '';
-export let hideSelectedIndicator = false;
-export let hideEmptyText = false;
-/** If true, the role for the popup menu will be 'menu' instead of the default 'listbox' value */
-export let usemenurole = false;
-let menuelement;
-const itemelements = [];
-let firstactive = 0;
-let lastactive = items.length - 1;
-$: hasMeaningfulItems = showSelected ? !!items.length : !!items.filter(itm => itm.value !== value).length;
-function hiddenItem(item) {
-    return !!item && !showSelected && item.value === value;
-}
-$: grouped = groupby(items, item => item.group ?? 'default-group');
-let itemsOrderedByGroup = [];
-function getItemIndex(item) {
+<script lang="ts" generics="MenuItem extends PopupMenuItem = PopupMenuItem">
+  import { createEventDispatcher, onDestroy, tick } from 'svelte'
+  import { groupby, isNull, randomid } from 'txstate-utils'
+  import { Store } from '@txstate-mws/svelte-store'
+  import { glue, portal } from '../actions'
+  import type { GlueAlignOpts, GlueAlignStore } from '../actions'
+  import type { PopupMenuItem, PopupMenuDivider } from '../types'
+  import ScreenReaderOnly from './ScreenReaderOnly.svelte'
+  import { getScrollParents, modifierKey } from '../util'
+  const dispatch = createEventDispatcher()
+
+  type MenuTypes = MenuItem | PopupMenuDivider
+
+  interface $$Events {
+    change: CustomEvent<MenuItem>
+  }
+
+  /** The DOM element that will act as the "button" for this menu. The menu will be placed next to the
+  button and be controlled by the button. Keyboard access will be enabled when the button has focus.
+  This component adds all appropriate attributes (tabindex, roles, and aria) automatically. */
+  export let buttonelement: HTMLElement | undefined
+  /** The list of menu items to be shown. Parent may change this at any time based on user activity. */
+  export let items: MenuItem[] = []
+  export let menushown = false
+  export let value: string | undefined = undefined
+  /** Control where the menu will appear. Default is to use the current viewport to make a decision to
+  maximize potential for menu growth. */
+  export let align: GlueAlignOpts = 'auto'
+  /** When the menu is active, should it cover the button or be rendered above/below it? */
+  export let cover = false
+  /** When an item is currently selected, should it appear in the menu (with a visual indicator), or
+  simply be removed from the list (`showSelected: false`). */
+  export let showSelected = true
+  /** When defined, this width will be passed through to the menu's CSS width. Use a valid CSS dimension
+  such as 33em or 159px. Generally this will be used when you need to match the menu width to something
+  else, like the button. If the width is static like 100% a simple CSS rule is likely more efficient. */
+  export let width: string | undefined = undefined
+  /** Bind this prop to receive a store that is updated each time a menu placement decision is made. Example
+  of when this is useful is when you are trying to round corners of your button and need to know whether the
+  menu is above or below your button so you know which corners to round and which to leave square. Note that
+  the values do not update when the menu is hidden, so you may need to rely on `menushown` as well. */
+  export let computedalign = new Store<GlueAlignStore>({ valign: 'bottom', halign: 'left' })
+  /** Create some spacing between the specified button element and the menu, in pixels */
+  export let gap = 0
+  /** Set to `true` if you want the parent element's styling to increase its minHeight when necessary. Useful
+  for parent elements not styled for variable size children and which you want override the the size of. */
+  export let adjustparentheight = false
+  /**  If the menu would be clipped by an `overflow: hidden`, you can set this prop and it will be placed in
+  the specified container, or the `document.body` if you simply say `true`. Placement will still be calculated
+  correctly since it uses positon fixed for placement. */
+  export let usePortal: HTMLElement | true | undefined = undefined
+  /** Useful for when your `items` need to be fetched but you want the associated element shown. Set to loading
+  until they're ready to be displayed and the popup menu will not be shown until the `loading` bind is `true`. */
+  export let loading = false
+  /** A bindable value for inspecting which item in `items` is currently highlighted as the item currently
+  active in the list. This is not the same as `value` and the highlighted item may or may not be selected as
+  for the `value` of the field. */
+  export let hilited: number | undefined = undefined
+  /** The id of the <ul> element that is the displayed list of items. */
+  export let menuid = randomid()
+  /** When there are no items (e.g. it's a filtered search and there were no results), we still display one
+  disabled item in the menu to let the user know what is going on. Use this prop to specify the message. */
+  export let emptyText: string | undefined = undefined
+  export let menuContainerClass = ''
+  export let menuClass = ''
+  export let menuItemClass = ''
+  export let menuItemHilitedClass = ''
+  export let menuItemSelectedClass = ''
+  export let menuCategoryClass = ''
+  export let hideSelectedIndicator = false
+  export let hideEmptyText = false
+  /** If true, the role for the popup menu will be 'menu' instead of the default 'listbox' value */
+  export let usemenurole = false
+
+  let menuelement: HTMLElement | undefined
+  const itemelements: HTMLElement[] = []
+  let firstactive = 0
+  let lastactive = items.length - 1
+  $: hasMeaningfulItems = showSelected ? !!items.length : !!items.filter(itm => itm.value !== value).length
+
+  function hiddenItem (item: MenuItem) {
+    return !!item && !showSelected && item.value === value
+  }
+
+  $: grouped = groupby(items, item => item.group ?? 'default-group')
+  let itemsOrderedByGroup: MenuItem[] = []
+
+  function getItemIndex (item: MenuItem) {
     return itemsOrderedByGroup.findIndex(itm => {
-        // need to handle default group options
-        if (itm.value === item.value) {
-            if (item.group === 'default-group') {
-                return isNull(itm.group);
-            }
-            else {
-                return item.group === itm.group;
-            }
+      // need to handle default group options
+      if (itm.value === item.value) {
+        if (item.group === 'default-group') {
+          return isNull(itm.group)
+        } else {
+          return item.group === itm.group
         }
-        return false;
-    });
-}
-async function reactToItems(..._) {
-    itemsOrderedByGroup = Object.values(grouped).flat();
-    firstactive = itemsOrderedByGroup.findIndex(itm => 'value' in itm && !itm.disabled && !hiddenItem(itm));
-    lastactive = itemsOrderedByGroup.length - [...itemsOrderedByGroup].reverse().findIndex(itm => 'value' in itm && !itm.disabled && !hiddenItem(itm)) - 1;
-    if (hilited && (itemsOrderedByGroup[hilited])?.disabled)
-        hilited = firstactive;
-}
-$: void reactToItems(items, value);
-async function reactToMenuShown(_) {
+      }
+      return false
+    })
+  }
+
+  async function reactToItems (..._: any[]) {
+    itemsOrderedByGroup = Object.values(grouped).flat()
+    firstactive = itemsOrderedByGroup.findIndex(itm => 'value' in itm && !itm.disabled && !hiddenItem(itm))
+    lastactive = itemsOrderedByGroup.length - [...itemsOrderedByGroup].reverse().findIndex(itm => 'value' in itm && !itm.disabled && !hiddenItem(itm)) - 1
+    if (hilited && (itemsOrderedByGroup[hilited])?.disabled) hilited = firstactive
+  }
+  $: void reactToItems(items, value)
+
+  async function reactToMenuShown (_: boolean) {
     if (!buttonelement) {
-        hilited = undefined;
-        return;
+      hilited = undefined
+      return
     }
-    await tick();
+    await tick()
     if (!menushown) {
-        buttonelement.removeAttribute('aria-controls');
-        buttonelement.removeAttribute('aria-owns');
-        buttonelement.setAttribute('aria-expanded', 'false');
-        if (hilited)
-            buttonelement.removeAttribute('aria-activedescendant');
-        hilited = undefined;
+      buttonelement.removeAttribute('aria-controls')
+      buttonelement.removeAttribute('aria-owns')
+      buttonelement.setAttribute('aria-expanded', 'false')
+      if (hilited) buttonelement.removeAttribute('aria-activedescendant')
+      hilited = undefined
+    } else {
+      if (buttonelement instanceof HTMLInputElement) buttonelement.setAttribute('aria-owns', menuid)
+      else buttonelement.setAttribute('aria-controls', menuid)
+      buttonelement.setAttribute('aria-expanded', 'true')
+      if (buttonelement !== document.activeElement) buttonelement.focus()
     }
-    else {
-        if (buttonelement instanceof HTMLInputElement)
-            buttonelement.setAttribute('aria-owns', menuid);
-        else
-            buttonelement.setAttribute('aria-controls', menuid);
-        buttonelement.setAttribute('aria-expanded', 'true');
-        if (buttonelement !== document.activeElement)
-            buttonelement.focus();
-    }
-}
-$: void reactToMenuShown(menushown);
-function move(idx) {
-    if (!menushown)
-        return;
-    if (itemsOrderedByGroup[idx] == null || (itemsOrderedByGroup[idx])?.disabled)
-        return;
-    hilited = Math.max(firstactive, Math.min(lastactive, idx));
-    itemelements[hilited].scrollIntoView({ block: 'center' });
-    buttonelement.setAttribute('aria-activedescendant', `${menuid}-${hilited}`);
-}
-function isSelectable(itm) {
-    return 'value' in itm && !itm.disabled && !hiddenItem(itm);
-}
-function onkeydown(e) {
-    if (modifierKey(e))
-        return;
+  }
+  $: void reactToMenuShown(menushown)
+
+  function move (idx: number) {
+    if (!menushown) return
+    if (itemsOrderedByGroup[idx] == null || (itemsOrderedByGroup[idx])?.disabled) return
+    hilited = Math.max(firstactive, Math.min(lastactive, idx))
+    itemelements[hilited].scrollIntoView({ block: 'center' })
+    buttonelement?.setAttribute('aria-activedescendant', `${menuid}-${hilited}`)
+  }
+
+  function isSelectable (itm: MenuTypes): itm is MenuItem {
+    return 'value' in itm && !itm.disabled && !hiddenItem(itm)
+  }
+
+  function onkeydown (e: KeyboardEvent) {
+    if (modifierKey(e)) return
     if (e.key === 'ArrowDown') {
-        e.preventDefault();
-        if (menushown) {
-            let i = (hilited ?? firstactive - 1) + 1;
-            while (itemsOrderedByGroup[i] && !isSelectable(itemsOrderedByGroup[i]))
-                i++;
-            move(i);
+      e.preventDefault()
+      if (menushown) {
+        let i = (hilited ?? firstactive - 1) + 1
+        while (itemsOrderedByGroup[i] && !isSelectable(itemsOrderedByGroup[i])) i += 1
+        move(i)
+      } else {
+        menushown = true
+        tick().then(() => { move(firstactive) }).catch(console.error)
+      }
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      if (menushown) {
+        let i = (hilited ?? lastactive + 1) - 1
+        while (itemsOrderedByGroup[i] && !isSelectable(itemsOrderedByGroup[i])) i -= 1
+        move(i)
+      } else {
+        menushown = true
+        tick().then(() => { move(lastactive) }).catch(console.error)
+      }
+    } else if (e.key === 'Home') {
+      e.preventDefault()
+      if (menushown) {
+        move(firstactive)
+      }
+    } else if (e.key === 'End') {
+      e.preventDefault()
+      if (menushown) {
+        move(lastactive)
+      }
+    } else if (e.key === 'Enter') {
+      e.preventDefault()
+      if (menushown) {
+        menushown = false
+        if (typeof hilited !== 'undefined') {
+          value = (itemsOrderedByGroup[hilited])?.value
+          dispatch('change', itemsOrderedByGroup[hilited])
         }
-        else {
-            menushown = true;
-            tick().then(() => { move(firstactive); }).catch(console.error);
+      } else {
+        menushown = true
+        tick().then(() => { move(firstactive) }).catch(console.error)
+      }
+    } else if (e.key === ' ') {
+      // buttonelement might be a text input if this popup is searchable,
+      // so we want to allow spaces to be entered without changing the menu situation
+      if (menushown) {
+        if (typeof hilited !== 'undefined') {
+          e.preventDefault()
+          menushown = false
+          value = (itemsOrderedByGroup[hilited])?.value
+          dispatch('change', itemsOrderedByGroup[hilited])
+        } else if (buttonelement?.tagName !== 'INPUT') {
+          e.preventDefault()
+          menushown = false
         }
+      } else if (buttonelement?.tagName !== 'INPUT') {
+        e.preventDefault()
+        menushown = true
+        tick().then(() => { move(firstactive) }).catch(console.error)
+      }
+    } else if (menushown && e.key === 'Escape') {
+      e.preventDefault()
+      e.stopPropagation()
+      menushown = false
     }
-    else if (e.key === 'ArrowUp') {
-        e.preventDefault();
-        if (menushown) {
-            let i = (hilited ?? lastactive + 1) - 1;
-            while (itemsOrderedByGroup[i] && !isSelectable(itemsOrderedByGroup[i]))
-                i--;
-            move(i);
-        }
-        else {
-            menushown = true;
-            tick().then(() => { move(lastactive); }).catch(console.error);
-        }
-    }
-    else if (e.key === 'Home') {
-        e.preventDefault();
-        if (menushown) {
-            move(firstactive);
-        }
-    }
-    else if (e.key === 'End') {
-        e.preventDefault();
-        if (menushown) {
-            move(lastactive);
-        }
-    }
-    else if (e.key === 'Enter') {
-        e.preventDefault();
-        if (menushown) {
-            menushown = false;
-            if (typeof hilited !== 'undefined') {
-                value = (itemsOrderedByGroup[hilited])?.value;
-                dispatch('change', itemsOrderedByGroup[hilited]);
-            }
-        }
-        else {
-            menushown = true;
-            tick().then(() => { move(firstactive); }).catch(console.error);
-        }
-    }
-    else if (e.key === ' ') {
-        // buttonelement might be a text input if this popup is searchable,
-        // so we want to allow spaces to be entered without changing the menu situation
-        if (menushown) {
-            if (typeof hilited !== 'undefined') {
-                e.preventDefault();
-                menushown = false;
-                value = (itemsOrderedByGroup[hilited])?.value;
-                dispatch('change', itemsOrderedByGroup[hilited]);
-            }
-            else {
-                if (buttonelement.tagName !== 'INPUT') {
-                    e.preventDefault();
-                    menushown = false;
-                }
-            }
-        }
-        else {
-            if (buttonelement.tagName !== 'INPUT') {
-                e.preventDefault();
-                menushown = true;
-                tick().then(() => { move(firstactive); }).catch(console.error);
-            }
-        }
-    }
-    else if (menushown && e.key === 'Escape') {
-        e.preventDefault();
-        e.stopPropagation();
-        menushown = false;
-    }
-}
-let blurTimer;
-function onbuttonclick(e) {
-    e.preventDefault();
-    cancelAnimationFrame(blurTimer);
-    menushown = !menushown;
-}
-function onblur(e) {
+  }
+
+  let blurTimer: number
+  function onbuttonclick (e: MouseEvent) {
+    e.preventDefault()
+    cancelAnimationFrame(blurTimer)
+    menushown = !menushown
+  }
+
+  function onblur (e: FocusEvent) {
     // tabindex=-1 on our menu elements means e.relatedTarget will be set
     if (!(e.relatedTarget instanceof HTMLElement && menuelement?.contains(e.relatedTarget))) {
-        blurTimer = requestAnimationFrame(() => { if (buttonelement !== document.activeElement)
-            menushown = false; });
+      blurTimer = requestAnimationFrame(() => { if (buttonelement !== document.activeElement) menushown = false })
     }
-}
-function oninput(e) {
-    if (document.activeElement === buttonelement)
-        menushown = true;
-}
-function cleanup(element) {
-    for (const observer of observers)
-        observer.disconnect();
-    observers = [];
+  }
+
+  function oninput (e: InputEvent) {
+    if (document.activeElement === buttonelement) menushown = true
+  }
+
+  function cleanup (element: HTMLElement | undefined) {
+    for (const observer of observers) observer.disconnect()
+    observers = []
     if (element) {
-        element.removeEventListener('click', onbuttonclick);
-        element.removeEventListener('keydown', onkeydown);
-        element.removeEventListener('blur', onblur);
-        element.removeEventListener('input', oninput);
-        element.removeAttribute('aria-disabled');
-        element.removeAttribute('aria-haspopup');
-        element.removeAttribute('aria-expanded');
-        element.removeAttribute('aria-controls');
-        element.removeAttribute('aria-activedescendant');
+      element.removeEventListener('click', onbuttonclick)
+      element.removeEventListener('keydown', onkeydown)
+      element.removeEventListener('blur', onblur)
+      element.removeEventListener('input', oninput)
+      element.removeAttribute('aria-disabled')
+      element.removeAttribute('aria-haspopup')
+      element.removeAttribute('aria-expanded')
+      element.removeAttribute('aria-controls')
+      element.removeAttribute('aria-activedescendant')
     }
-}
-onDestroy(() => { cleanup(buttonelement); });
-// if buttonelement changes we need to handle listeners and aria
-let lastbuttonelement;
-let observers = [];
-function reactToButtonElement(buttonelement) {
-    cleanup(lastbuttonelement);
-    lastbuttonelement = buttonelement;
+  }
+
+  onDestroy(() => { cleanup(buttonelement) })
+
+  // if buttonelement changes we need to handle listeners and aria
+  let lastbuttonelement: HTMLElement | undefined
+  let observers: IntersectionObserver[] = []
+  function reactToButtonElement (buttonelement: HTMLElement | undefined) {
+    cleanup(lastbuttonelement)
+    lastbuttonelement = buttonelement
     if (buttonelement) {
-        buttonelement.setAttribute('aria-haspopup', (usemenurole ? 'true' : 'listbox'));
-        buttonelement.setAttribute('aria-expanded', menushown ? 'true' : 'false');
-        if (!usemenurole) {
-            buttonelement.setAttribute('role', 'combobox');
-        }
-        buttonelement.addEventListener('click', onbuttonclick);
-        buttonelement.addEventListener('keydown', onkeydown);
-        buttonelement.addEventListener('blur', onblur);
-        buttonelement.addEventListener('input', oninput);
-        const parents = getScrollParents(buttonelement);
-        for (const parent of [...parents, undefined]) {
-            const observer = new IntersectionObserver((entries) => {
-                for (const entry of entries) {
-                    if (entry.intersectionRatio < 0.1)
-                        menushown = false;
-                }
-            }, { root: parent, threshold: 0.1 });
-            observer.observe(buttonelement);
-            observers.push(observer);
-        }
+      buttonelement.setAttribute('aria-haspopup', (usemenurole ? 'true' : 'listbox'))
+      buttonelement.setAttribute('aria-expanded', menushown ? 'true' : 'false')
+      if (!usemenurole) {
+        buttonelement.setAttribute('role', 'combobox')
+      }
+      buttonelement.addEventListener('click', onbuttonclick)
+      buttonelement.addEventListener('keydown', onkeydown)
+      buttonelement.addEventListener('blur', onblur)
+      buttonelement.addEventListener('input', oninput)
+      const parents = getScrollParents(buttonelement)
+      for (const parent of [...parents, undefined]) {
+        const observer = new IntersectionObserver(entries => {
+          for (const entry of entries) {
+            if (entry.intersectionRatio < 0.1) menushown = false
+          }
+        }, { root: parent, threshold: 0.1 })
+        observer.observe(buttonelement)
+        observers.push(observer)
+      }
     }
-}
-$: reactToButtonElement(buttonelement);
-const onclick = (item) => (e) => {
-    e.stopPropagation();
-    e.preventDefault();
-    if (item.disabled)
-        return;
-    menushown = false;
-    value = item.value;
-    dispatch('change', item);
-};
-$: hasSelected = showSelected && !hideSelectedIndicator && items.some(itm => 'value' in itm && itm.value === value);
+  }
+  $: reactToButtonElement(buttonelement)
+
+  const onclick = (item: MenuItem) => (e: MouseEvent) => {
+    e.stopPropagation()
+    e.preventDefault()
+    if (item.disabled) return
+    menushown = false
+    value = item.value
+    dispatch('change', item)
+  }
+
+  $: hasSelected = showSelected && !hideSelectedIndicator && items.some(itm => 'value' in itm && itm.value === value)
 </script>
 
 {#if menushown && !loading && (hasMeaningfulItems || !hideEmptyText)}
-  <div use:portal={usePortal === true ? undefined : (usePortal || null)} use:glue={{ target: buttonelement, align, cover, gap, adjustparentheight, store: computedalign }} class={menuContainerClass}>
+  <div use:portal={usePortal === true ? undefined : (usePortal ?? null)} use:glue={{ target: buttonelement, align, cover, gap, adjustparentheight, store: computedalign }} class={menuContainerClass}>
     <ul bind:this={menuelement} id={menuid} role={usemenurole ? 'menu' : 'listbox'} tabindex="-1" style={width ? `width: ${width}` : ''} class={menuClass} class:hasSelected class:defaultmenu={!menuClass && !menuContainerClass} on:keydown={onkeydown}>
-      {#each Object.entries(grouped) as [group, groupitems]}
+      {#each Object.entries(grouped) as [group, groupitems] (group)}
         {#if group === 'default-group'}
           {#each groupitems as item, i (item.value)}
             {@const itemIndex = getItemIndex(item)}