@txstate-mws/svelte-components 1.4.6 → 1.4.7

package/dist/components/Card.svelte

@@ -1,3 +1,6 @@
+<!-- @component
+  [`Card`](https://github.com/txstate-etc/svelte-components/blob/main/src/lib/components/Card.svelte)
+-->
 <script>export let className = '';
 import { getContext } from 'svelte';
 import { resize, passActions } from '../actions';

package/dist/components/Card.svelte.d.ts

@@ -15,6 +15,7 @@ declare const __propDef: {
 export type CardProps = typeof __propDef.props;
 export type CardEvents = typeof __propDef.events;
 export type CardSlots = typeof __propDef.slots;
+/** [`Card`](https://github.com/txstate-etc/svelte-components/blob/main/src/lib/components/Card.svelte) */
 export default class Card extends SvelteComponentTyped<CardProps, CardEvents, CardSlots> {
 }
 export {};

package/dist/components/CardLayout.svelte

@@ -1,3 +1,6 @@
+<!-- @component
+  [`CardLayout`](https://github.com/txstate-etc/svelte-components/blob/main/src/lib/components/CardLayout.svelte)
+-->
 <script>import { onDestroy, tick, setContext, onMount } from 'svelte';
 import { writable } from 'svelte/store';
 import { resize, passActions } from '../actions';

package/dist/components/CardLayout.svelte.d.ts

@@ -18,6 +18,7 @@ declare const __propDef: {
 export type CardLayoutProps = typeof __propDef.props;
 export type CardLayoutEvents = typeof __propDef.events;
 export type CardLayoutSlots = typeof __propDef.slots;
+/** [`CardLayout`](https://github.com/txstate-etc/svelte-components/blob/main/src/lib/components/CardLayout.svelte) */
 export default class CardLayout extends SvelteComponentTyped<CardLayoutProps, CardLayoutEvents, CardLayoutSlots> {
 }
 export {};

package/dist/components/CollapsingTable.svelte

@@ -1,3 +1,10 @@
+<!-- @component
+[Collapsing Table](https://github.com/txstate-etc/svelte-components/blob/main/docs/CollapsingTable.md)
+
+This component is meant to help make tables responsive by eliminating columns (from the right) as the screen width reduces.
+When there are hidden columns, the last column header becomes a dropdown button allowing the selection of another column
+to be displayed instead.
+-->
 <script>import { Store } from '@txstate-mws/svelte-store';
 import { derived } from 'svelte/store';
 import { classes } from '../util';

package/dist/components/CollapsingTable.svelte.d.ts

@@ -54,6 +54,13 @@ declare const __propDef: {
 export type CollapsingTableProps = typeof __propDef.props;
 export type CollapsingTableEvents = typeof __propDef.events;
 export type CollapsingTableSlots = typeof __propDef.slots;
+/**
+ * [Collapsing Table](https://github.com/txstate-etc/svelte-components/blob/main/docs/CollapsingTable.md)
+ *
+ * This component is meant to help make tables responsive by eliminating columns (from the right) as the screen width reduces.
+ * When there are hidden columns, the last column header becomes a dropdown button allowing the selection of another column
+ * to be displayed instead.
+ */
 export default class CollapsingTable extends SvelteComponentTyped<CollapsingTableProps, CollapsingTableEvents, CollapsingTableSlots> {
 }
 export {};

package/dist/components/ConditionalWrapper.svelte

@@ -1,3 +1,27 @@
+<!-- @component
+[Conditional Wrapper](https://github.com/txstate-etc/svelte-components/blob/main/docs/ConditionalWrapper.md)
+Sometimes you want to wrap a complex bit of HTML in a certain element based on a condition,
+and not wrap it at all if the condition isn't met. Without help, this situation results in a
+lot of duplicate code because you have to have an if/else block outside the whole thing, and
+the complex HTML goes in both branches:
+```svelte
+{#if shouldwrap}
+  <div class="wrapper">
+    ... a whole bunch of html ...
+  </div>
+{:else}
+  ... a whole bunch of html, again ...
+{/if}
+```
+With this component, you can de-duplicate like this:
+```svelte
+<ConditionalWrapper class="wrapper" condition={shouldwrap}>
+  ... a whole bunch of html ...
+</ConditionalWrapper>
+```
+Any props you provide (except the ConditionalWrapper props like `condition`) will pass through
+to the wrapper element/component, if it gets inserted.
+-->
 <script>export let condition;
 export let component = undefined;
 export let a = false;

package/dist/components/ConditionalWrapper.svelte.d.ts

@@ -3,7 +3,7 @@ declare const __propDef: {
     props: {
         [x: string]: any;
         condition: boolean | undefined;
-        component?: Function | undefined;
+        component?: any | undefined;
         a?: boolean;
         span?: boolean;
         element?: HTMLElement | undefined;
@@ -18,6 +18,30 @@ declare const __propDef: {
 export type ConditionalWrapperProps = typeof __propDef.props;
 export type ConditionalWrapperEvents = typeof __propDef.events;
 export type ConditionalWrapperSlots = typeof __propDef.slots;
+/**
+ * [Conditional Wrapper](https://github.com/txstate-etc/svelte-components/blob/main/docs/ConditionalWrapper.md)
+ * Sometimes you want to wrap a complex bit of HTML in a certain element based on a condition,
+ * and not wrap it at all if the condition isn't met. Without help, this situation results in a
+ * lot of duplicate code because you have to have an if/else block outside the whole thing, and
+ * the complex HTML goes in both branches:
+ * ```svelte
+ * {#if shouldwrap}
+ * <div class="wrapper">
+ *   ... a whole bunch of html ...
+ * </div>
+ * {:else}
+ * ... a whole bunch of html, again ...
+ * {/if}
+ * ```
+ * With this component, you can de-duplicate like this:
+ * ```svelte
+ * <ConditionalWrapper class="wrapper" condition={shouldwrap}>
+ * ... a whole bunch of html ...
+ * </ConditionalWrapper>
+ * ```
+ * Any props you provide (except the ConditionalWrapper props like `condition`) will pass through
+ * to the wrapper element/component, if it gets inserted.
+ */
 export default class ConditionalWrapper extends SvelteComponentTyped<ConditionalWrapperProps, ConditionalWrapperEvents, ConditionalWrapperSlots> {
 }
 export {};

package/dist/components/FocusLock.svelte

@@ -1,3 +1,17 @@
+<!-- @component
+The [`FocusLock`](https://github.com/txstate-etc/svelte-components/blob/main/docs/Modal.md#FocusLock)
+component is for creating accessible modal dialogs that do not have a darkened backdrop. It shares the
+(`escapable`, `hidefocus`, `hidefocuslabel`, `initialfocus`, `returnfocusto`, and `includeselector`)
+props and the behaviors with `Modal` because the `Modal` component uses a `FocusLock` itself. In additon
+it exports a `className` prop for passing the component a custom CSS class name to use.
+
+Any time the `FocusLock` is in the DOM, it will lock screen readers inside it. You release them by
+removing it from the DOM. Regular users are NOT trapped and may interact with other screen elements.
+When they do, the escape event will be fired, allowing you to remove the dialog.
+
+`FocusLock`s can be nested. The user will be trapped inside the deepest `FocusLock` present in the DOM.
+When it goes away, they'll be trapped inside the previous `FocusLock`, and so on.
+-->
 <script context="module">export const FocusLockStack = [];
 const waitAtick = typeof requestAnimationFrame !== 'undefined' ? resolve => requestAnimationFrame(resolve) : resolve => resolve(0);
 </script>
@@ -7,18 +21,16 @@ export let hidefocus = true;
 export let hidefocuslabel = 'focus is above modal dialog, start tabbing';
 export let initialfocus = undefined;
 export let returnfocusto = undefined;
-/**
- * If you expect any popup menus to be added to the body, we need to know that they
- * are considered to be part of the focus lock, or else the modal will be dismissed
- * when the user clicks inside
- * use commas to include multiple selectors
- */
+/** If you expect any popup menus to be added to the body, we need to know that they
+are considered to be part of the focus lock, or else the modal will be dismissed
+when the user clicks inside. Use commas to include multiple selectors. */
 export let includeselector = undefined;
 let className = '';
 export { className as class };
+export let focusId = randomid();
 import { onMount, onDestroy, createEventDispatcher, tick } from 'svelte';
 import { tabbable } from 'tabbable';
-import { sleep } from 'txstate-utils';
+import { randomid, sleep } from 'txstate-utils';
 import { buttonify } from '../actions';
 import ScreenReaderOnly from './ScreenReaderOnly.svelte';
 const dispatch = createEventDispatcher();
@@ -32,10 +44,12 @@ onMount(async () => {
     if (prevFocusLock)
         prevFocusLock.pause();
     FocusLockStack.push({
+        focusId,
         pause: () => { state = 'paused'; },
         unpause: () => { if (state === 'paused')
             state = 'active'; }
     });
+    dispatch('focuslockupdate');
     if (typeof returnfocusto === 'undefined') {
         returnfocusto = document.querySelector(':focus');
     }
@@ -64,10 +78,13 @@ onDestroy(async () => {
     if (returnfocusto && wasactive) {
         returnfocusto.focus();
     }
-    FocusLockStack.pop();
+    const idx = FocusLockStack.findIndex(f => f.focusId === focusId);
+    if (idx > -1)
+        FocusLockStack.splice(idx, 1);
     const prevFocusLock = FocusLockStack.slice(-1)[0];
     if (prevFocusLock)
         prevFocusLock.unpause();
+    dispatch('focuslockupdate');
 });
 const setInitialFocus = () => {
     const firstfocus = lockelement ? tabbable(lockelement)[0] : undefined;

package/dist/components/FocusLock.svelte.d.ts

@@ -1,5 +1,6 @@
 import { SvelteComponentTyped } from "svelte";
 export declare const FocusLockStack: {
+    focusId: string;
     pause: () => void;
     unpause: () => void;
 }[];
@@ -10,18 +11,17 @@ declare const __propDef: {
         hidefocuslabel?: string;
         initialfocus?: string | undefined;
         returnfocusto?: HTMLElement | null | undefined;
-        /**
-           * If you expect any popup menus to be added to the body, we need to know that they
-           * are considered to be part of the focus lock, or else the modal will be dismissed
-           * when the user clicks inside
-           * use commas to include multiple selectors
-           */ includeselector?: string | undefined;
+        /** If you expect any popup menus to be added to the body, we need to know that they
+          are considered to be part of the focus lock, or else the modal will be dismissed
+          when the user clicks inside. Use commas to include multiple selectors. */ includeselector?: string | undefined;
         class?: string;
+        focusId?: string;
     };
     events: {
         click: MouseEvent;
         mousedown: MouseEvent;
         escape: CustomEvent<any>;
+        focuslockupdate: CustomEvent<any>;
     } & {
         [evt: string]: CustomEvent<any>;
     };
@@ -32,6 +32,20 @@ declare const __propDef: {
 export type FocusLockProps = typeof __propDef.props;
 export type FocusLockEvents = typeof __propDef.events;
 export type FocusLockSlots = typeof __propDef.slots;
+/**
+ * The [`FocusLock`](https://github.com/txstate-etc/svelte-components/blob/main/docs/Modal.md#FocusLock)
+ * component is for creating accessible modal dialogs that do not have a darkened backdrop. It shares the
+ * (`escapable`, `hidefocus`, `hidefocuslabel`, `initialfocus`, `returnfocusto`, and `includeselector`)
+ * props and the behaviors with `Modal` because the `Modal` component uses a `FocusLock` itself. In additon
+ * it exports a `className` prop for passing the component a custom CSS class name to use.
+ *
+ * Any time the `FocusLock` is in the DOM, it will lock screen readers inside it. You release them by
+ * removing it from the DOM. Regular users are NOT trapped and may interact with other screen elements.
+ * When they do, the escape event will be fired, allowing you to remove the dialog.
+ *
+ * `FocusLock`s can be nested. The user will be trapped inside the deepest `FocusLock` present in the DOM.
+ * When it goes away, they'll be trapped inside the previous `FocusLock`, and so on.
+ */
 export default class FocusLock extends SvelteComponentTyped<FocusLockProps, FocusLockEvents, FocusLockSlots> {
 }
 export {};

package/dist/components/Loading.svelte

@@ -1,3 +1,8 @@
+<!-- @component
+  The purpose of `Loading` is to provide a visual, as well as Screen Reader friendly, cueue that associated content is loading
+  until the slotted content is signals it is done loading via the `loading` boolean bind at which point the slotted content
+  will be rendered.
+-->
 <script>import { afterUpdate } from 'svelte';
 import ScreenReaderOnly from './ScreenReaderOnly.svelte';
 import { resize, ResizeStore } from '../actions';

package/dist/components/Loading.svelte.d.ts

@@ -14,6 +14,11 @@ declare const __propDef: {
 export type LoadingProps = typeof __propDef.props;
 export type LoadingEvents = typeof __propDef.events;
 export type LoadingSlots = typeof __propDef.slots;
+/**
+ * The purpose of `Loading` is to provide a visual, as well as Screen Reader friendly, cueue that associated content is loading
+ * until the slotted content is signals it is done loading via the `loading` boolean bind at which point the slotted content
+ * will be rendered.
+ */
 export default class Loading extends SvelteComponentTyped<LoadingProps, LoadingEvents, LoadingSlots> {
 }
 export {};

package/dist/components/Lottie.svelte

@@ -1,3 +1,7 @@
+<!-- @component
+  The purpose of `Lottie` is to provide a [Lottie](https://www.npmjs.com/package/lottie-web) player element
+  with Screen Reader compatible attributes and lables readily available through the `alt` prop.
+-->
 <script>import { onMount } from 'svelte';
 import { isBlank } from 'txstate-utils';
 import ScreenReaderOnly from './ScreenReaderOnly.svelte';
@@ -9,6 +13,7 @@ export let direction = 1;
 export let paused = false;
 export let width = undefined;
 export let height = undefined;
+/** `<ScreenReaderOnly>` lable to be applied. */
 export let alt = '';
 let container;
 let animation;

package/dist/components/Lottie.svelte.d.ts

@@ -9,7 +9,7 @@ declare const __propDef: {
         paused?: boolean;
         width?: string | undefined;
         height?: string | undefined;
-        alt?: string;
+        /** `<ScreenReaderOnly>` lable to be applied. */ alt?: string;
     };
     events: {
         [evt: string]: CustomEvent<any>;
@@ -19,6 +19,10 @@ declare const __propDef: {
 export type LottieProps = typeof __propDef.props;
 export type LottieEvents = typeof __propDef.events;
 export type LottieSlots = typeof __propDef.slots;
+/**
+ * The purpose of `Lottie` is to provide a [Lottie](https://www.npmjs.com/package/lottie-web) player element
+ * with Screen Reader compatible attributes and lables readily available through the `alt` prop.
+ */
 export default class Lottie extends SvelteComponentTyped<LottieProps, LottieEvents, LottieSlots> {
 }
 export {};

package/dist/components/Modal.svelte

@@ -1,4 +1,15 @@
-<script>export let opaque = false;
+<!-- @component
+The [`Modal`](https://github.com/txstate-etc/svelte-components/blob/main/docs/Modal.md#Modal) component is designed to block out the screen and focus the user on the content inside the Modal.
+
+It provides only the backdrop and a scrollable container for your content. If your content should have a background color, be sure to add it yourself.
+
+Any time the Modal is in the DOM, it will take over the screen. You make it go away by removing it from the DOM.
+-->
+<script>import { createEventDispatcher, onMount } from 'svelte';
+import { randomid } from 'txstate-utils';
+import FocusLock, { FocusLockStack } from './FocusLock.svelte';
+import { portal } from '../actions';
+export let opaque = false;
 export let containerClass = '';
 export let escapable = true;
 export let hidefocus = true;
@@ -6,23 +17,21 @@ export let hidefocuslabel = undefined;
 export let initialfocus = undefined;
 export let returnfocusto = undefined;
 export let usePortal = undefined;
-/**
- * If you expect any popup menus to be added to the body, we need to know that they
- * are considered to be part of the focus lock, or else the modal will be dismissed
- * when the user clicks inside
- * use commas to include multiple selectors
- */
+/** If you expect any popup menus to be added to the body, we need to know that they
+are considered to be part of the focus lock, or else the modal will be dismissed
+when the user clicks inside. Use commas to include multiple selectors. */
 export let includeselector = undefined;
-import { createEventDispatcher, onMount } from 'svelte';
-import FocusLock, { FocusLockStack } from './FocusLock.svelte';
-import { portal } from '../actions';
+export let focusId = randomid();
 const dispatch = createEventDispatcher();
 const endmodal = () => {
     dispatch('escape');
 };
 let stackPosition;
+function onFocusLockUpdate() {
+    stackPosition = FocusLockStack.findIndex(f => f.focusId === focusId);
+}
 onMount(() => {
-    stackPosition = FocusLockStack.length - 1;
+    onFocusLockUpdate();
     document.body.style.marginRight = (window.innerWidth - document.body.clientWidth) + 'px';
     document.body.style.overflow = 'hidden';
     return () => {
@@ -34,7 +43,7 @@ onMount(() => {
 
 <!-- svelte-ignore a11y-click-events-have-key-events -->
 <div use:portal={usePortal} class="modal-backdrop" style:--modal-z={stackPosition * 10 + 3000} class:opaque on:mousedown|stopPropagation|preventDefault={() => escapable && endmodal()}>
-  <FocusLock class="modal-container {containerClass}" {includeselector} {escapable} on:escape {hidefocus} {hidefocuslabel} {returnfocusto} {initialfocus}>
+  <FocusLock bind:focusId class="modal-container {containerClass}" {includeselector} {escapable} on:escape {hidefocus} {hidefocuslabel} {returnfocusto} {initialfocus} on:focuslockupdate={onFocusLockUpdate}>
     <slot></slot>
   </FocusLock>
 </div>

package/dist/components/Modal.svelte.d.ts

@@ -9,12 +9,10 @@ declare const __propDef: {
         initialfocus?: string | undefined;
         returnfocusto?: HTMLElement | undefined;
         usePortal?: HTMLElement | undefined;
-        /**
-           * If you expect any popup menus to be added to the body, we need to know that they
-           * are considered to be part of the focus lock, or else the modal will be dismissed
-           * when the user clicks inside
-           * use commas to include multiple selectors
-           */ includeselector?: string | undefined;
+        /** If you expect any popup menus to be added to the body, we need to know that they
+          are considered to be part of the focus lock, or else the modal will be dismissed
+          when the user clicks inside. Use commas to include multiple selectors. */ includeselector?: string | undefined;
+        focusId?: string;
     };
     events: {
         escape: CustomEvent<any>;
@@ -28,6 +26,13 @@ declare const __propDef: {
 export type ModalProps = typeof __propDef.props;
 export type ModalEvents = typeof __propDef.events;
 export type ModalSlots = typeof __propDef.slots;
+/**
+ * The [`Modal`](https://github.com/txstate-etc/svelte-components/blob/main/docs/Modal.md#Modal) component is designed to block out the screen and focus the user on the content inside the Modal.
+ *
+ * It provides only the backdrop and a scrollable container for your content. If your content should have a background color, be sure to add it yourself.
+ *
+ * Any time the Modal is in the DOM, it will take over the screen. You make it go away by removing it from the DOM.
+ */
 export default class Modal extends SvelteComponentTyped<ModalProps, ModalEvents, ModalSlots> {
 }
 export {};

package/dist/components/MultiSelect.svelte

@@ -1,22 +1,39 @@
+<!-- @component
+  The purpose of `MultiSelect` is to provide a text input associated with a popup menu that
+  displays, or completes, choice selections based on what's been typed in the text input.
+  Selected choices will be added to a list of selected items, in a pill format, that provides
+  a means for tracking and removing existing selections. The choices listed in the popup are
+  controlled by the parent component via the `getOptions` function that will be used as a
+  debounced callback on the contents of the text input.
+-->
 <script>import { createEventDispatcher } from 'svelte';
 import { randomid, Cache } from 'txstate-utils';
 import ScreenReaderOnly from './ScreenReaderOnly.svelte';
 import DefaultPopupMenu from './PopupMenu.svelte';
 import { modifierKey, selectionIsLeft } from '../util';
-export let id = randomid();
 export let name;
-export let disabled = false;
+/**
+ * Function to pass to the component that tells it how to use the text
+ * in the text input to determine what `PopupMenuItem[]` should be displayed
+ * in the `PopupMenu`. Items already 'selected' from the popup menu will be
+ * tracked and automatically filtered from the popup if returned as one of the
+ * `PopupMenuItem[]` by `getOptions`. */
 export let getOptions;
+export let id = randomid();
+export let disabled = false;
 export let menuContainerClass = undefined;
 export let menuClass = undefined;
 export let menuItemClass = undefined;
 export let menuItemHilitedClass = undefined;
+export let inputClass = undefined;
+/** The maximum number of selections allowed before making new selections is disabled. Default of 0 is unlimited. */
 export let maxSelections = 0;
 export let selected = [];
 export let placeholder = '';
 export let emptyText = undefined;
 export let usePortal = undefined;
 export let descid = undefined;
+/** You can define your own PopupMenu and pass for that to be used or accept DefaultPopupMenu. */
 export let PopupMenu = DefaultPopupMenu;
 let menushown;
 let loading = false;
@@ -30,6 +47,7 @@ const optionsCache = new Cache(async (ipt) => {
     return await getOptions(ipt);
 }, { freshseconds: 5 });
 $: selectedSet = new Set(selected.map(s => s.value));
+// Stop showing our menu if the maxSelections limit has been reached.
 $: if (maxSelections > 1 && selected.length >= maxSelections && menushown)
     menushown = false;
 let optionsTimer;
@@ -127,8 +145,8 @@ $: reactToHilite(hilitedpill, id);
         <ScreenReaderOnly>, click to deselect</ScreenReaderOnly>
       </li>
     {/each}
-    <li class="input">
-      <input type="text" id={id} name={name} {disabled} placeholder={placeholder}
+    <li class={`input ${inputClass ?? ''}`}>
+      <input type="text" {id} {name} {disabled} {placeholder}
         bind:this={inputelement} bind:value={inputvalue} on:blur
         on:focus={inputfocus} on:keydown={inputkeydown}
         autocomplete="off" autocorrect="off" spellcheck="false" aria-autocomplete="list"
@@ -141,7 +159,9 @@ $: reactToHilite(hilitedpill, id);
   </ScreenReaderOnly>
   <slot></slot>
 </fieldset>
-<svelte:component this={PopupMenu} bind:menushown bind:hilited={popuphilited} bind:value={popupvalue} align='bottomleft' {usePortal} {loading} {emptyText} {menuContainerClass} {menuClass} {menuItemClass} {menuItemHilitedClass} items={options} buttonelement={inputelement} on:change={addSelection}></svelte:component>
+<svelte:component this={PopupMenu} bind:menushown bind:hilited={popuphilited} bind:value={popupvalue} align='bottomleft'
+ {usePortal} {loading} {emptyText} {menuContainerClass} {menuClass} {menuItemClass} {menuItemHilitedClass} items={options} buttonelement={inputelement}
+ on:change={addSelection}/>
 
 <style>
   fieldset {

package/dist/components/MultiSelect.svelte.d.ts

@@ -3,15 +3,21 @@ import DefaultPopupMenu from './PopupMenu.svelte';
 import type { PopupMenuItem } from '../types';
 declare const __propDef: {
     props: {
-        id?: string;
         name: string;
+        /**
+           * Function to pass to the component that tells it how to use the text
+           * in the text input to determine what `PopupMenuItem[]` should be displayed
+           * in the `PopupMenu`. Items already 'selected' from the popup menu will be
+           * tracked and automatically filtered from the popup if returned as one of the
+           * `PopupMenuItem[]` by `getOptions`. */ getOptions: (search: string) => Promise<PopupMenuItem[]> | PopupMenuItem[];
+        id?: string;
         disabled?: boolean;
-        getOptions: (search: string) => Promise<PopupMenuItem[]> | PopupMenuItem[];
         menuContainerClass?: string | undefined;
         menuClass?: string | undefined;
         menuItemClass?: string | undefined;
         menuItemHilitedClass?: string | undefined;
-        maxSelections?: number;
+        inputClass?: string | undefined;
+        /** The maximum number of selections allowed before making new selections is disabled. Default of 0 is unlimited. */ maxSelections?: number;
         selected?: {
             value: string;
             label: string;
@@ -20,7 +26,7 @@ declare const __propDef: {
         emptyText?: string | undefined;
         usePortal?: HTMLElement | true | undefined;
         descid?: string | undefined;
-        PopupMenu?: typeof DefaultPopupMenu;
+        /** You can define your own PopupMenu and pass for that to be used or accept DefaultPopupMenu. */ PopupMenu?: typeof DefaultPopupMenu;
     };
     events: {
         blur: FocusEvent;
@@ -35,6 +41,14 @@ declare const __propDef: {
 export type MultiSelectProps = typeof __propDef.props;
 export type MultiSelectEvents = typeof __propDef.events;
 export type MultiSelectSlots = typeof __propDef.slots;
+/**
+ * The purpose of `MultiSelect` is to provide a text input associated with a popup menu that
+ * displays, or completes, choice selections based on what's been typed in the text input.
+ * Selected choices will be added to a list of selected items, in a pill format, that provides
+ * a means for tracking and removing existing selections. The choices listed in the popup are
+ * controlled by the parent component via the `getOptions` function that will be used as a
+ * debounced callback on the contents of the text input.
+ */
 export default class MultiSelect extends SvelteComponentTyped<MultiSelectProps, MultiSelectEvents, MultiSelectSlots> {
 }
 export {};

package/dist/components/PopupMenu.svelte

@@ -1,3 +1,7 @@
+<!-- @component
+  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>import { createEventDispatcher, onDestroy, tick } from 'svelte';
 import { randomid } from 'txstate-utils';
 import { Store } from '@txstate-mws/svelte-store';
@@ -5,20 +9,49 @@ import { glue, portal } from '../actions';
 import ScreenReaderOnly from './ScreenReaderOnly.svelte';
 import { 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' });
+/** 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, unless there are scrolling containers between the button and the menu. */
 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 = '';
@@ -200,8 +233,12 @@ $: hasSelected = showSelected && items.some(itm => itm.value === value);
 </script>
 
 {#if menushown}
-  <div use:portal={usePortal === true ? undefined : (usePortal || null)} use:glue={{ target: buttonelement, align, cover, adjustparentheight, store: computedalign }} class={menuContainerClass}>
-    <ul bind:this={menuelement} id={menuid} role='listbox' style={width ? `width: ${width}` : ''} class={menuClass} class:hasSelected class:defaultmenu={!menuClass && !menuContainerClass} on:keydown={onkeydown}>
+  <div use:portal={usePortal === true ? undefined : (usePortal || null)}
+       use:glue={{ target: buttonelement, align, cover, adjustparentheight, store: computedalign }}
+       class={menuContainerClass}>
+    <ul bind:this={menuelement} id={menuid} role='listbox' style={width ? `width: ${width}` : ''}
+        class={menuClass} class:hasSelected class:defaultmenu={!menuClass && !menuContainerClass}
+        on:keydown={onkeydown}>
       {#each items as item, i (item.value)}
         {#if showSelected || item.value !== value}
           <!-- svelte-ignore a11y-click-events-have-key-events -->

package/dist/components/PopupMenu.svelte.d.ts

@@ -4,21 +4,37 @@ import type { GlueAlignOpts, GlueAlignStore } from '../actions';
 import type { PopupMenuItem } from '../types';
 declare const __propDef: {
     props: {
-        buttonelement: HTMLElement;
-        items?: PopupMenuItem[];
+        /** 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. */ buttonelement: HTMLElement;
+        /** The list of menu items to be shown. Parent may change this at any time based on user activity. */ items?: PopupMenuItem[];
         menushown?: boolean;
         value?: string | undefined;
-        align?: GlueAlignOpts;
-        cover?: boolean;
-        showSelected?: boolean;
-        width?: string | undefined;
-        computedalign?: Store<GlueAlignStore>;
-        adjustparentheight?: boolean;
-        usePortal?: HTMLElement | true | undefined;
-        loading?: boolean;
-        hilited?: number | undefined;
-        menuid?: string;
-        emptyText?: string | undefined;
+        /** Control where the menu will appear. Default is to use the current viewport to make a decision to
+          maximize potential for menu growth. */ align?: GlueAlignOpts;
+        /** When the menu is active, should it cover the button or be rendered above/below it? */ cover?: boolean;
+        /** 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`). */ showSelected?: boolean;
+        /** 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. */ width?: string | 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. */ computedalign?: Store<GlueAlignStore>;
+        /** 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. */ adjustparentheight?: boolean;
+        /**  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, unless there are scrolling containers between the button and the menu. */ usePortal?: HTMLElement | true | 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`. */ loading?: boolean;
+        /** 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. */ hilited?: number | undefined;
+        /** The id of the <ul> element that is the displayed list of items. */ menuid?: string;
+        /** 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. */ emptyText?: string | undefined;
         menuContainerClass?: string;
         menuClass?: string;
         menuItemClass?: string;
@@ -43,6 +59,10 @@ declare const __propDef: {
 export type PopupMenuProps = typeof __propDef.props;
 export type PopupMenuEvents = typeof __propDef.events;
 export type PopupMenuSlots = typeof __propDef.slots;
+/**
+ * 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.
+ */
 export default class PopupMenu extends SvelteComponentTyped<PopupMenuProps, PopupMenuEvents, PopupMenuSlots> {
 }
 export {};

package/dist/components/ScreenReaderOnly.svelte

@@ -1,18 +1,9 @@
 <!-- @component
   This component is for adding text that can be read by screen readers while remaining invisible to regular users.
-  ```svelte
-  <ScreenReaderOnly {id} {arialive} {ariaatomic}>
-    {`Some descriptive text to be read about the component by screen readers.`}
-  </ScreenReaderOnly>
-  ```
-  #### Properties
-  ```ts
-  id?: string|undefined = undefined // Any ID you'd like to bind to the underlying <span>.
-  arialive?: 'off'|'assertive'|'polite'|undefined = undefined
-  ariaatomic?: boolean|'false'|'true'|undefined = undefined
-  ```
+  Useful for when aria-label isn't supported with the drawback that it can show up in copy/paste selections.
 -->
-<script>export let id = undefined;
+<script>/** An id to bind with the `<span>` used to implement this component. */
+export let id = undefined;
 export let arialive = undefined;
 export let ariaatomic = undefined;
 </script>

package/dist/components/ScreenReaderOnly.svelte.d.ts

@@ -1,7 +1,7 @@
 import { SvelteComponentTyped } from "svelte";
 declare const __propDef: {
     props: {
-        id?: string | undefined;
+        /** An id to bind with the `<span>` used to implement this component. */ id?: string | undefined;
         arialive?: 'off' | 'assertive' | 'polite' | undefined;
         ariaatomic?: boolean | 'false' | 'true' | undefined;
     };
@@ -17,17 +17,7 @@ export type ScreenReaderOnlyEvents = typeof __propDef.events;
 export type ScreenReaderOnlySlots = typeof __propDef.slots;
 /**
  * This component is for adding text that can be read by screen readers while remaining invisible to regular users.
- * ```svelte
- * <ScreenReaderOnly {id} {arialive} {ariaatomic}>
- *   {`Some descriptive text to be read about the component by screen readers.`}
- * </ScreenReaderOnly>
- * ```
- * #### Properties
- * ```ts
- * id?: string|undefined = undefined // Any ID you'd like to bind to the underlying <span>.
- * arialive?: 'off'|'assertive'|'polite'|undefined = undefined
- * ariaatomic?: boolean|'false'|'true'|undefined = undefined
- * ```
+ * Useful for when aria-label isn't supported with the drawback that it can show up in copy/paste selections.
  */
 export default class ScreenReaderOnly extends SvelteComponentTyped<ScreenReaderOnlyProps, ScreenReaderOnlyEvents, ScreenReaderOnlySlots> {
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@txstate-mws/svelte-components",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "description": "Svelte components that are generically useful.",
   "scripts": {
     "prepublishOnly": "svelte-package",