@txstate-mws/svelte-components 0.0.66 → 1.0.2

package/dist/ts/lib/derivedstore.d.ts

@@ -1,16 +1,23 @@
-import { DeepStore, UsableSubject } from './deepstore';
+import { Store } from './store';
+import { UsableSubject } from './activestore';
+export interface DerivedStoreOptions {
+    debounce?: number | boolean;
+}
 /**
  * Watch one or more parent stores for changes. Each time, run a function to derive
  * a new state from the parent state(s). Subscribers will only be notified if the
  * derived state has changed (uses fast-deep-equal).
  *
  * If only one parent store, it's possible to use a dot-prop string as the getter.
- *
- * If you create one of these in a component, be sure to call .complete() in onDestroy
- * to free up memory.
  */
-export declare class DerivedStore<DerivedType, ParentType = any> extends DeepStore<DerivedType> {
-    constructor(store: UsableSubject<ParentType>, getter: (value: ParentType) => DerivedType);
-    constructor(store: UsableSubject<ParentType>, getter: string);
-    constructor(store: UsableSubject<any>[], getter: (value: any[]) => DerivedType);
+export declare class DerivedStore<DerivedType, ParentType = any> extends Store<DerivedType> {
+    constructor(store: UsableSubject<ParentType> | UsableSubject<any>[], getter: string | ((value: any) => DerivedType) | ((values: any[]) => DerivedType), options?: DerivedStoreOptions);
 }
+export declare function derivedStore<DerivedType, ParentType, A extends keyof ParentType>(store: UsableSubject<ParentType>, accessor: A, options?: DerivedStoreOptions): DerivedStore<ParentType[A], ParentType>;
+export declare function derivedStore<DerivedType, ParentType = any>(store: UsableSubject<ParentType>, accessor: string, options?: DerivedStoreOptions): DerivedStore<DerivedType, ParentType>;
+export declare function derivedStore<DerivedType, ParentType>(store: UsableSubject<ParentType>, getter: (value: ParentType) => DerivedType, options?: DerivedStoreOptions): DerivedStore<DerivedType, ParentType>;
+export declare function derivedStore<DerivedType, T1, T2>(store: [UsableSubject<T1>, UsableSubject<T2>], getter: (value: [T1, T2]) => DerivedType, options?: DerivedStoreOptions): DerivedStore<DerivedType>;
+export declare function derivedStore<DerivedType, T1, T2, T3>(store: [UsableSubject<T1>, UsableSubject<T2>, UsableSubject<T3>], getter: (value: [T1, T2, T3]) => DerivedType, options?: DerivedStoreOptions): DerivedStore<DerivedType>;
+export declare function derivedStore<DerivedType, T1, T2, T3, T4>(store: [UsableSubject<T1>, UsableSubject<T2>, UsableSubject<T3>, UsableSubject<T4>], getter: (value: [T1, T2, T3, T4]) => DerivedType, options?: DerivedStoreOptions): DerivedStore<DerivedType>;
+export declare function derivedStore<DerivedType, T1, T2, T3, T4, T5>(store: [UsableSubject<T1>, UsableSubject<T2>, UsableSubject<T3>, UsableSubject<T4>, UsableSubject<T5>], getter: (value: [T1, T2, T3, T4, T5]) => DerivedType, options?: DerivedStoreOptions): DerivedStore<DerivedType>;
+export declare function derivedStore<DerivedType>(store: UsableSubject<any>[], getter: (value: any[]) => DerivedType, options?: DerivedStoreOptions): DerivedStore<DerivedType>;

package/dist/ts/lib/index.d.ts

@@ -1,7 +1,9 @@
 export * from './bodyoffset';
-export * from './deepstore';
+export * from './convertedstore';
 export * from './derivedstore';
+export * from './activestore';
 export * from './repositioned';
 export * from './safestore';
+export * from './store';
 export * from './substore';
 export * from './util';

package/dist/ts/lib/safestore.d.ts

@@ -1,4 +1,4 @@
-import { DeepStore } from './deepstore';
-export declare class SafeStore<T> extends DeepStore<T> {
+import { Store } from './store';
+export declare class SafeStore<T> extends Store<T> {
     clone(value: T): T;
 }

package/dist/ts/lib/store.d.ts

@@ -0,0 +1,16 @@
+import { ActiveStore } from './activestore';
+/**
+ * An alternative to svelte's "writable" that also checks deep equality (fast-deep-equal) before
+ * notifying subscribers. A writable will notify subscribers after a shallow equality check, which
+ * only works for scalars.
+ *
+ * Note that this strategy is weak against mutable state updates:
+ * store.update(v => { v.someprop = 'newvalue'; return v })
+ *
+ * This line would NOT notify subscribers because the state will be compared against
+ * itself and always found to be equal. If you are making updates in a mutable fashion,
+ * use a SafeStore instead.
+ */
+export declare class Store<T> extends ActiveStore<T> {
+    equal(a: T, b: T): boolean;
+}

package/dist/ts/lib/substore.d.ts

@@ -1,4 +1,5 @@
-import { DeepStore, WritableSubject } from './deepstore';
+import { Store } from './store';
+import { WritableSubject } from './activestore';
 /**
  * Create a store that represents a part of a larger store. Updates to the parent store will propagate
  * down to the SubStore as appropriate, and updates to the SubStore will propagate
@@ -10,14 +11,14 @@ import { DeepStore, WritableSubject } from './deepstore';
  * generated. For example, a parent store containing state { deep: { value: 'here' }, hello: 'world' }
  * could be used with the getter string "deep.value". The SubStore's initial state would be "here", and
  * updating it to "there" would update the parent store state to { deep: { value: 'there' }, hello: 'world' }
- *
- * If you create one of these in a component, be sure to call .complete() in onDestroy to free up memory.
  */
-export declare class SubStore<SubType, ParentType = any> extends DeepStore<SubType> {
+export declare class SubStore<SubType, ParentType = any> extends Store<SubType> {
     protected parentStore: WritableSubject<ParentType>;
     protected setter: (value: SubType, state: ParentType) => ParentType;
-    constructor(store: WritableSubject<ParentType>, getter: string);
-    constructor(store: WritableSubject<ParentType>, getter: (value: ParentType) => SubType, setter: (value: SubType, state: ParentType) => ParentType);
+    constructor(store: WritableSubject<ParentType>, getter: keyof ParentType | string | ((value: ParentType) => SubType), setter?: (value: SubType, state: ParentType) => ParentType);
     set(value: SubType): void;
     clone(state: SubType): any;
 }
+export declare function subStore<SubType, ParentType, A extends keyof ParentType>(store: WritableSubject<ParentType>, accessor: A): SubStore<ParentType[A], ParentType>;
+export declare function subStore<SubType, ParentType = any>(store: WritableSubject<ParentType>, accessor: string): SubStore<SubType, ParentType>;
+export declare function subStore<SubType, ParentType>(store: WritableSubject<ParentType>, getter: (value: ParentType) => SubType, setter: (value: SubType, state: ParentType) => ParentType): SubStore<SubType, ParentType>;

package/dist/ts/tests/Modal/ModalTest.svelte

@@ -4,7 +4,7 @@
 </script>
 
 {#if shown}
-<Modal initialfocus='input[type="submit"]' on:dismiss={() => shown = false}>
+<Modal on:escape={() => shown = false}>
   <form>
     <div class="formfield">
       <label for="firstname">First Name:</label><input id="firstname" type="text" name="firstname">
@@ -23,7 +23,7 @@
   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer tempus nulla ut nulla auctor, quis sodales massa laoreet. Duis erat lacus, gravida vitae massa vel, semper accumsan urna. Morbi gravida dui sit amet sodales luctus. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Vestibulum eget pulvinar dui. Vivamus quis eros eu ex semper consectetur nec at elit. Praesent faucibus arcu a nisi semper, eu tempus felis vehicula. Suspendisse potenti.</p>
 
   <p>Donec luctus nulla mattis ipsum aliquam imperdiet. Vestibulum nec finibus enim. Proin et arcu arcu. Quisque feugiat leo velit, vitae mollis felis ornare sed. Suspendisse sollicitudin, libero sed ullamcorper finibus, diam turpis eleifend velit, ut suscipit orci mauris id purus. Donec dapibus facilisis mauris a venenatis. Maecenas gravida velit maximus nibh tincidunt, eget auctor tellus efficitur. Aenean varius tristique lacus, sit amet placerat sem tempor at. Sed imperdiet fermentum nibh, sit amet tempor est cursus ac.</p>
-  <button on:click={() => shown = true}>Show Modal</button>
+  <button data-testid="button" on:click={() => shown = true}>Show Modal</button>
   <p>Praesent augue magna, maximus at mattis eget, euismod nec neque. Phasellus ut dolor a turpis molestie fermentum. Phasellus condimentum, ipsum sed rutrum maximus, diam ex ultrices sapien, quis iaculis nisi arcu at turpis. Morbi aliquam mattis posuere. Integer pretium diam diam, non lobortis quam consectetur laoreet. Sed posuere blandit venenatis. Nulla gravida maximus arcu non consectetur.</p>
 
   <p>Cras egestas massa mattis dictum imperdiet. Nulla bibendum nisl ipsum, ut scelerisque arcu consectetur vitae. Integer convallis id nunc sit amet faucibus. Maecenas suscipit diam orci, ac suscipit dolor convallis sed. Mauris vel tellus eget nunc mattis faucibus sit amet sed lorem. Cras lobortis, massa at vestibulum dignissim, quam tellus sagittis purus, eget dictum dolor quam in leo. Aliquam condimentum, ante sit amet semper laoreet, lacus est scelerisque mi, nec mollis diam massa et massa. Donec sagittis massa quis diam dictum, sit amet convallis mauris tincidunt. Nam vulputate ligula quis ex condimentum, in sollicitudin dolor accumsan. Donec volutpat dui in faucibus tempus. Proin vitae tincidunt ex. Proin ut ultricies diam. Praesent sed purus in purus efficitur fermentum vulputate quis dolor. Morbi viverra quam ac dolor facilisis consectetur.</p>

package/dist/ts/tests/PopupMenu/PopupMenuSimple.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
+  import { hashify } from 'txstate-utils'
   import PopupMenu from '../../components/PopupMenu.svelte'
-  let button: HTMLElement
 
   export let showSelected = false
   export let items = [
@@ -12,12 +12,18 @@
     { value: '5', label: 'Friday' },
     { value: '6', label: 'Saturday', disabled: true }
   ]
+
+  let button: HTMLElement
+  let value: string
+  $: itemsByValue = hashify(items, 'value')
+  $: selected = itemsByValue[value]
 </script>
 
 <div class="topspacer"></div>
 <div class="container">
   <button data-testid="button" class="ui gold button" bind:this={button}>Popup Menu</button>
-  <PopupMenu buttonelement={button} {items} {showSelected}></PopupMenu>
+  <div>selected: {#if selected}{selected.value}, {selected.label}{:else}none{/if}</div>
+  <PopupMenu bind:value buttonelement={button} {items} {showSelected}></PopupMenu>
 </div>
 
 <style>

package/docs/CollapsingTable.md

@@ -21,12 +21,7 @@ A `config` prop allows you to pass an array of column definitions. If passed, on
   the column that is most identifying for each row, like a name.
   by default the leftmost column will stick around as identifying
 * `bodyCellClass?: string` CSS class to set on `td` elements in the body area
-  `item`, `key`, and `value` as props. The value will also be placed inside your component's
-  default slot as a bare string.
 * `headerCellClass?: string` CSS class to set on `td` elements in the header row
-  `column`, `key`, and `title` as props, where `column` is this configuration object, and `title`
-  is reliable (uses `key` if configuration had no `title`). The title/key will also be placed
-  inside your component's default slot as a bare string.
 
 ## Optional Props
  * `tableClass` CSS class for the `table`
@@ -43,12 +38,12 @@ A `config` prop allows you to pass an array of column definitions. If passed, on
 Lots of slots are provided for extra configuration.
 
 ### Default Slot
-The default slot is used for each table cell in the body area. Because of the way slots work, your
-content will always be executed in every cell. So if you need to do something special for just one
-cell, you have to use an if/else block to identify the special cell, falling back to {value} for
-everything else:
+The default slot is used for each table cell in the body area. It is optional and falls back to {value}.
+Because of the way slots work, your slot content will be executed in every cell. So if you need to do
+something special for just one cell, you have to use an if/else block to identify the special cell,
+falling back to {value} for everything else:
 ```svelte
-<CollapsingTable items={myItems} let:key let:value>
+<CollapsingTable items={myItems} let:item let:key let:value>
   {#if key === 'myspecialkey'}
     <MySpecialComponent>{value}</MySpecialComponent>
   {:else}
@@ -56,11 +51,12 @@ everything else:
   {/if}
 </CollapsingTable>
 ```
+The slot props are `item`, `key`, and `value`.
 ### Header Cell Slot
 A slot named `headercell` allows you to do the same thing for cells in the header row that the
 default slot allows for body cells.
 ```svelte
-<CollapsingTable items={myItems} let:key let:title>
+<CollapsingTable items={myItems} let:column let:key let:title>
   <div slot="headercell">
     {#if key === 'myspecialkey'}
       <MySpecialComponent>{title}</MySpecialComponent>
@@ -70,11 +66,14 @@ default slot allows for body cells.
   </div>
 </CollapsingTable>
 ```
+The slot props are `column`, `key`, and `title`. `column` is the configuration object for the
+current column, `title` is `column.title || column.key`. The title/key will be used as fallback
+content if you do not specify a header slot.
 ### Dropdown Icon Slot
 A slot is provided for you to provide a custom icon for the column header that is serving as the
 dropdown button.
 ```svelte
-<CollapsingTable items={myItems} let:key let:value>
+<CollapsingTable items={myItems}>
   <i type='fa caret-down' slot="dropicon" aria-hidden="true"></i>
 </CollapsingTable>
 ```

package/docs/ConditionalWrapper.md

@@ -0,0 +1,35 @@
+# Conditional Wrapper
+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.
+
+## Props
+* `condition: boolean|undefined` (required) - Whether or not to wrap the element. Accepts `undefined`
+  for convenience when evaluating presence of an optional variable.
+* `component?: SvelteComponent` (optional) - The wrapper will be a svelte component instead of a DOM
+  element. Props all get passed through.
+* `a: boolean` (optional) - The wrapper will be a link element.
+* `span: boolean` (optional) - The wrapper will be a span element.
+* `element?: HTMLElement` (for binding) - If the wrapper is a DOM element, bind this prop to get a
+  reference to wrapper element (if it exists). If the wrapper is a svelte component, this will be
+  passed to it as a prop so that the wrapper component can bind it to a DOM element.
+
+If none of `a`, `span`, or `component` props are specified, the default is to create a `div` wrapper.

package/docs/Modal.md

@@ -0,0 +1,63 @@
+# Modal
+The 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.
+
+## Example Usage
+```svelte
+<script>
+  let showMyModal = false
+</script>
+<button on:click={() => showMyModal = true}>Show Modal</button>
+{#if showMyModal}
+  <Modal on:escape={() => showMyModal = false}>
+    This is a modal dialog!
+  </Modal>
+{/if}
+<style>
+  :global(.modal-container) { background: white; }
+</style>
+```
+## Custom Events
+* `on:escape` - dispatched when the user does something that would normally dismiss a modal, such as clicking in the darkened backdrop or pressing the Escape key. You should listen for this and dismiss your modal. If you do not listen for this event, users will only be able to escape by some other means provided within your content. Be careful not to trap them!
+
+## Props
+* `opaque: boolean` (default `false`) - Make the backdrop completely opaque so that it cannot be seen through. This is a more jarring experience for users but sometimes you don't want background content to be visible at all.
+* `containerClass: string` (default `''`) - A class to be added to the scrollable container inside the backdrop. This container will always have the `.modal-container` class regardless of this prop.
+* `escapable: boolean` (default `true`) - Let screen readers know that they can escape the modal by pressing the Escape key. If you are not listening for `on:escape` then you should set this `false` to avoid giving screen reader users false information.
+* `hidefocus: boolean` (default `true`) - Focus must be moved to the modal when it opens, in order to maintain accessibility. This component avoids making the focus visible to users by default as it might be visually disconcerting. So on mount, focus is moved to an invisible element above your content. If you prefer focus to be visible to users, set this to `false` and focus will automatically be moved to the first element in your content that has a tabindex and therefore be visible to users. This prop is overridden if you provide an `initialfocus`.
+* `hidefocuslabel: string` (default `focus is above modal dialog, start tabbing`) - The message that will be read out to users using a screen reader when the focus is on the invisible element created by the `hidefocus` prop.
+* `initialfocus: string` (default `undefined`) - A selector to be used to locate and set focus on an element in your content, on mount. Use if you want focus on a specific element when the modal opens. Overrides `hidefocus`.
+* `returnfocusto: HTMLElement` (default element that had focus was when modal opened) - Use to control where focus moves when the modal closes. If not provided, component automatically saves the element that had focus on mount. Usually it's the button that triggered the modal.
+
+# FocusLock
+The FocusLock component is for creating accessible modal dialogs that do not have a darkened backdrop. It shares many props and behaviors with Modal because the Modal component uses a FocusLock itself.
+
+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.
+
+FocusLocks 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.
+
+## Custom Events
+* `on:escape` - dispatched when the user does something to dismiss the dialog, such as pressing the Escape key or clicking outside the dialog area. You should listen for this and remove the FocusLock. If you do not listen for this event, users will only be able to escape by some other means provided within your content. Be careful not to trap them!
+
+## Example Usage
+```svelte
+<script>
+  let showMyDialog = false
+</script>
+<button on:click={() => showMyDialog = true}>Show Dialog</button>
+{#if showMyDialog}
+  <FocusLock on:escape={() => showMyDialog = false}>
+    Screen readers cannot escape this!
+    <button on:click={() => showMyDialog = false}>Collapse Dialog</button>
+  </FocusLock>
+{/if}
+```
+## Props
+* `escapable: boolean` (default `true`) - Controls whether the focus lock can be easily escaped by pressing the Escape key or clicking the invisible focus (see `hidefocus`). If you set this `false` you must provide a way to dismiss the lock inside your content or screen readers will be trapped.
+* `hidefocus: boolean` (default `true`) - Focus must be moved to the modal when it opens, in order to maintain accessibility. This component avoids making the focus visible to users by default as it might be visually disconcerting. So on mount, focus is moved to an invisible element above your content. If you prefer focus to be visible to users, set this to `false` and focus will automatically be moved to the first element in your content that has a tabindex and therefore be visible to users. This prop is overridden if you provide an `initialfocus`.
+* `hidefocuslabel: string` (default `focus is above modal dialog, start tabbing`) - The message that will be read out to users using a screen reader when the focus is on the invisible element created by the `hidefocus` prop.
+* `initialfocus: string` (default `undefined`) - A selector to be used to locate and set focus on an element in your content, on mount. Use if you want focus on a specific element when the lock mounts. Overrides `hidefocus`.
+* `returnfocusto: HTMLElement` (default element that had focus was when focuslock mounted) - Use to control where focus moves when the lock ends. If not provided, component automatically saves the element that had focus on mount. Usually it's the button that triggered the dialog.

package/docs/PopupMenu.md

@@ -0,0 +1,31 @@
+# PopupMenu
+
+This component is meant to display a menu of options to the user, activated by clicking
+any element. It can also be controlled from the parent, by binding the `menushown` boolean.
+
+## Props
+* `buttonelement: HTMLElement` (required) - 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.
+* `items: PopupMenuItem[]` (required) - The list of menu items to be shown. Parent may change this at any time based on user activity.
+* `menushown?: boolean` (default `false`) - Bind this prop to track/change the visible state of the menu from the parent.
+* `value?: string` (default no selection) - Bind this prop to track/change the currently selected value from the parent.
+* `align?: GlueAlignOpts` (default `auto`) - Control where the menu will appear. Default is to use the current viewport to make a decision to maximize potential for menu growth.
+* `cover?: boolean` (default `false`) - When the menu is active, should it cover the button or be rendered above/below it?
+* `showSelected?: boolean` (default `true`) - 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`)?
+* `width?: string` (default `undefined`) - 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.
+* `computedalign: readable<{ valign: 'top'|'bottom', halign: 'left'|'right' }>` (default store is provided) - 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.
+* `usePortal?: HTMLElement|true` (default `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.
+* `emptyText?: string` (default `¯\_(ツ)_/¯`) - 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.
+* `menuContainerClass?: string` (default `''`) - CSS class to pass through so you can do extra styling work
+* `menuClass?: string` (default `''`) - CSS class to pass through so you can do extra styling work
+* `menuItemClass?: string` (default `''`) - CSS class to pass through so you can do extra styling work
+* `menuItemHilitedClass?: string` (default `''`) - CSS class to pass through so you can do extra styling work
+* `menuItemSelectedClass?: string` (default `''`) - CSS class to pass through so you can do extra styling work
+
+## Events
+* `on:change` - Dispatched any time a new value is selected. Does not fire when you change the `value` property from the outside. Event detail will be the full PopupMenuItem object that was selected.
+
+## Types
+* `PopupMenuItem: { value: string, label?: string, disabled?: boolean }` - Each item must have a unique non-empty value. Display label is optional, as is a `disabled` status that will show the item in the list but not allow users to hilite or select it.
+
+## Disabling
+Since there are so many different possibilities for the button you attach to, the PopupMenu does not have a `disabled` prop. If the PopupMenu should be disabled, simply remove it from the DOM with an `{#if}` block. Remember to also set `aria-disabled` on your button and likely provide some visual indicators like `cursor: default` or the `disabled` attribute on elements that support it.

package/docs/ScreenReaderOnly.md

@@ -0,0 +1,10 @@
+# ScreenReaderOnly
+This component is for adding text that can be read to screen readers while remaining
+invisible to regular users. It accepts `arialive` and `ariaatomic` props to pass through to
+the corresponding HTML attributes. It also accepts an `id` prop in case you need to
+point at it with an aria-describedby attribute on some other element.
+
+Using this component is often better than using aria-label because aria-label still has poor support
+and sometimes is not good enough to make WAVE happy with an empty icon-link. It's also a
+good way to add additional text when sighted users have a little text already, e.g. to add
+interactivity instructions.

package/docs/actions.md

@@ -1,10 +1,84 @@
 # Actions
 
+## use:buttonify
+This action turns any HTML element into an accessible button that responds to keyboard events and has
+role="button" and the tabindex attribute set. You are still responsible for making sure it has
+readable content or a good label. Does NOT change styling at all.
+```svelte
+<div use:buttonify on:click={onClick}>You can tab to me and click me with the Enter key</div>
+```
+
 ## use:glue
-This action glues the element it is placed on to the target specified, with a specified alignment option. The element is placed in document.body so that it cannot be constrained or hidden by overflow:hidden, then it is positioned to match the target element. It is most useful for dropdown or autocomplete menus.
+This action glues the element it is placed on to the target specified, with a specified alignment
+option. It is most useful for dropdown or autocomplete menus.
+
+The element should have `position: absolute` on it already. It is not moved to a new place in the DOM,
+it just gets `top`/`left`/`bottom`/`right` properties set.
+
+If you have problems with the glued element being clipped by a parent with `overflow: hidden`, you
+may combine it with the `use:portal` action to move it somewhere else; `use:glue` will recalculate
+for the new location.
+
+If you do not specify an `align` setting, the default is `auto`, which will evaluate the current
+viewport and determine which alignment gives the glued element the most space to grow.
 ```svelte
 <button bind:this={menubutton}>Activate Menu</button>
-<ul use:glue={{ element: menubutton, align: 'bottomright' }}>
+<ul use:glue={{ target: menubutton, align: 'bottomright' }}>
   <li>Menu Item 1</li>
   <li>Menu Item 2</li>
+</ul>
+```
+
+## use:offset
+This action allows you to observe any DOM element's position in the body. You pass in a svelte store
+and it will be updated when the element moves.
+
+Another configuration option is `debounce: number`, which will debounce the updates for the specified
+number of milliseconds. Use this option if you will make a complicated calculation after each update and do not
+want to perform the calculation multiple times during a single animation or while the user is resizing
+their viewport/window. It will defer the updates until the animation or resizing stops for at least `debounce`
+milliseconds.
+```svelte
+<script>
+  const offset = writable({ top: 0, left: 0, bottom: 0, right: 0 })
+</script>
+<div use:offset={{ store: offset }}>distance between me and body top is {$offset.top}</div>
+```
+
+## use:portal
+This action allows you to move an element to a new place in the DOM upon mount. It's useful when your component
+is sensitive to getting clipped by parents with overflow: hidden or for anything like a modal or toast message
+that needs to be positioned relative to the body, but created within a smaller component, like a web form.
+
+For convenience, the default is to move it to `document.body` when you `use:portal` without any config:
+```svelte
+<div use:portal>I'm in the body now!</div>
+```
+If you are accepting an optional target as a prop, this may cause unexpected behavior where your parent component
+declines to pass a portal target, but your element ends up in `document.body`. To prevent this, you may pass `null`
+instead of `undefined`, and the element will stay where it was before the change to `null`:
+```svelte
+<script>
+  export let portaltarget = undefined
+</script>
+<div use:portal={portaltarget || null}></div>
+```
+
+## use:resize
+This action allows you to observe an element's width and height with the `ResizeObserver`. Svelte has a built-in
+`bind:clientWidth` functionality, but it works by inserting an invisible iframe into the DOM for each observation,
+which is a little ugly and potentially slow.
+
+You pass in a svelte store and it will be updated when the element's size changes.
+
+Another configuration option is `debounce: number`, which will debounce the updates for the specified
+number of milliseconds. Use this option if you will make a complicated calculation after each update and do not
+want to perform the calculation multiple times during a single animation or while the user is resizing
+their viewport/window. It will defer the updates until the animation or resizing stops for at least `debounce`
+milliseconds.
+```svelte
+<script>
+  const size = writable({ clientWidth: 100, clientHeight: 100, offsetWidth: 100, offsetHeight: 100 })
+</script>
+<div use:offset={{ store: size }}>My dimensions are {$size.offsetWidth}x{$size.offsetHeight}</div>
 ```