@txstate-mws/svelte-components 1.0.4 → 1.1.0

package/.eslintrc.cjs

@@ -0,0 +1,37 @@
+module.exports = {
+	root: true,
+	parser: '@typescript-eslint/parser',
+	extends: 'standard-with-typescript',
+	plugins: ['svelte3', '@typescript-eslint'],
+	ignorePatterns: ['*.cjs', 'package/**/*', 'svelte.config.js', 'playwright.config.js'],
+	overrides: [{ files: ['*.svelte'], processor: 'svelte3/svelte3' }],
+	settings: {
+		'svelte3/typescript': () => require('typescript')
+	},
+  rules: {
+    'import/first': 'off',
+		'no-multiple-empty-lines': 'off',
+    'no-undef-init': 'off',
+		'no-unused-vars': 'off',
+		'no-use-before-define': 'off',
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/array-type': 'off',
+    '@typescript-eslint/no-non-null-assertion': 'off',
+    '@typescript-eslint/no-unused-vars': 'off', // typescript does this better
+    '@typescript-eslint/require-await': 'off',
+    '@typescript-eslint/return-await': ['error', 'always'],
+    '@typescript-eslint/strict-boolean-expressions': 'off',
+    '@typescript-eslint/prefer-readonly': ['off']
+  },
+	parserOptions: {
+		project: './tsconfig.json',
+		sourceType: 'module',
+		extraFileExtensions: ['.svelte'],
+		ecmaVersion: 2020
+	},
+	env: {
+		browser: true,
+		es2017: true,
+		node: true
+	}
+};

package/docs/CollapsingTable.md

@@ -0,0 +1,79 @@
+# Collapsing Table
+
+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.
+
+# Usage
+
+The only required prop is an `items` array of objects. Column headers will automatically be detected from object keys if no column configuration is present.
+
+## Column Configuration
+
+A `config` prop allows you to pass an array of column definitions. If passed, only these columns will appear, other keys in your `items` objects will be ignored.
+
+### Variables accepted for each column
+
+* `key: string` corresponds to object key in your `items` objects
+* `title?: string` a display name for this column's header
+* `width?: number` a guess at how wide in pixels this column will be; helps decide when to hide
+                   columns, default 150
+* `neverhide?: boolean`<br>
+  setting to make sure this column is never hidden; good to set 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
+* `headerCellClass?: string` CSS class to set on `td` elements in the header row
+
+## Optional Props
+ * `tableClass` CSS class for the `table`
+ * `bodyRowClass` CSS class for `tr` in the body area
+ * `bodyCellClass` CSS class for `td` in the body area, additional to the one set in column config
+ * `headerRowClass` CSS class for `tr` on the header row
+ * `headerCellClass` CSS class for `th` in the header row, additional to the one set in column config
+ * `menuClass` CSS class for the `ul` dropdown menu
+ * `menuItemClass` CSS class for `li` in the dropdown menu
+ * `menuItemHilitedClass` CSS class for `li` in the dropdown menu when they are currently hilited/active
+ * `defaultCellWidth`, guess for any column width in pixels, allows you to hide columns earlier/later, default 150
+
+## Slots
+Lots of slots are provided for extra configuration.
+
+### Default Slot
+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:item let:key let:value>
+  {#if key === 'myspecialkey'}
+    <MySpecialComponent>{value}</MySpecialComponent>
+  {:else}
+    {value}
+  {/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:column let:key let:title>
+  <div slot="headercell">
+    {#if key === 'myspecialkey'}
+      <MySpecialComponent>{title}</MySpecialComponent>
+    {:else}
+      {title}
+    {/if}
+  </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}>
+  <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

@@ -0,0 +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. 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={{ 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>
+```

package/docs/stores.md

@@ -0,0 +1,203 @@
+# Overview
+A set of stores to complement svelte stores. These stores perform deep equality checks on the data before updating subscribers, and are easy to subclass and add mutation methods.
+
+## Subclassing
+The most effective way to use a store is to create a Store subclass with mutation
+methods. If you're familiar with redux, these methods would be similar to actions on
+reducers.
+```typescript
+interface MyState {
+  foo: string
+  more: string
+}
+class MyStore extends Store<MyState> {
+  updateFoo (newfoo: string) {
+    // do some business logic here
+    newfoo = newfoo.trim().toLocaleLowerCase()
+    this.set({ ...this.value, foo: newfoo })
+  }
+}
+const store = new MyStore({ foo: 'bar', more: 'state' })
+store.updateFoo('baz')
+```
+This way your store controls all the business logic and your components can be truly
+reactive.
+
+Note that `this.value` contains the current version of the store. You can also use the
+`store.update` method to have the current value passed to you.
+
+### Asynchronous mutations
+Mutation methods become even more powerful when you do asynchronous updates. All of
+your asynchronous code can be encapsulated in a single method, making it much easier
+to think about how you want to handle race conditions and errors. Redux toolkit would
+call these `thunk` functions, but here they are just another method.
+```typescript
+interface BookState {
+  loading?: boolean
+  book?: Book
+  error?: string
+}
+class BookStore extends Store<BookState> {
+  async getBook (id: number) {
+    if (this.value.loading) return // one book at a time!
+    this.set({ loading: true, book: undefined, error: undefined })
+    try {
+      const book = await api.getBook(id)
+      this.set({ loading: false, book, error: undefined })
+    } catch (e) {
+      this.set({ loading: false, book: undefined, error: e.message })
+    }
+  }
+}
+```
+
+### Creating and sharing store instances
+It's up to you to determine how you'd like to create and share stores. The singleton
+pattern works great for end user applications. For instance, a global error store can
+help individual components communicate with the layout component when they experience
+a problem that's fatal for the page. Creating a singleton store for each screen in your
+application is another powerful pattern and helps all your components share the screen
+state.
+
+Context can be very convenient as well. The main benefit of putting a store in Context
+is it can be garbage collected when the context owner is unmounted. In SSR scenarios,
+global stores can leak between clients unless you're careful to reset them on each request,
+so storing in Context can be safer.
+
+Similarly, a store can be created in a component and passed down as a prop, enabling
+efficient two-way communication with its children. The main advantage over binding a
+property is that the components can share the mutation methods.
+
+## Store Types
+
+### Store
+This is the basic store type and performs deep equality checks before notifying subscribers.
+It is intended to contain simple JSON state that is easy to programmatically explore. By
+default, you are expected to update the store with fresh or cloned objects:
+```typescript
+const initialState = { foo: 'bar', more: 'state' }
+const store = new Store(initialState)
+store.update(state => ({ ...state, foo: 'baz' }))
+```
+### SafeStore
+If it's not convenient to clone your objects, you can use a `SafeStore` instead,
+which will allow you to mutate your state and then call `set` on it:
+```typescript
+const initialState = { foo: 'bar', more: 'state' }
+const store = new SafeStore(initialState)
+initialState.foo = 'baz'
+store.set(initialState) // with a regular Store, this would not notify subscribers
+```
+This is only designed to work on pure JSON (objects and arrays, not Maps, Sets, or
+any other data types). There is a slight performance cost due to deep cloning.
+
+### ActiveStore
+This is a store that does no equality checks before notifying subscribers. It can save a couple
+CPU cycles by skipping the deep equality check, but may be an overall performance degradation
+if subscribers are doing significant work and there are many updates that do not change the state.
+It is also vulnerable to unexpected infinite loops if subscribers end up triggering a redundant
+`set` command. This store is safe to use with mutated objects and is the only one that can
+handle non-JSON objects in the state.
+
+### SubStore
+This is a store that makes it convenient to interact with a portion of a larger store. You
+subscribe to a parent store in the constructor, and when you update the SubStore, your
+changes will be sent to the parent store.
+
+#### Getter / Setter version of SubStore
+This requires both a getter and setter function to handle each direction. The setter is given
+the new SubStore state and the existing parent store state and should return a new state for
+the parent store.
+```typescript
+const parentStore = new Store({
+  about: { header: 'About' },
+  events: { header: 'Events' }
+})
+const aboutStore = new SubStore(parentStore, pState => pState.about, (newAboutState, pState) => ({ ...pState, about: newAboutState }))
+aboutStore.set({ header: 'About Us' })
+// aboutStore state is { header: 'About Us' }
+// parentStore state is { about: { header: 'About Us' }, events: { header: 'Events' } }
+```
+
+#### Accessor string version of SubStore
+Alternatively, a dot-prop accessor string can be provided and both the getter and setter will be
+automatically generated.
+```typescript
+const parentStore = new Store({
+  about: { header: 'About' },
+  events: { header: 'Events' }
+})
+const aboutStore = subStore(parentStore, 'about')
+aboutStore.set({ header: 'About Us' })
+// aboutStore state is { header: 'About Us' }
+// parentStore state is { about: { header: 'About Us' }, events: { header: 'Events' } }
+```
+Note the use of a `subStore` function rather than `new SubStore`. `new SubStore` will work just
+fine, but since typescript (at the time of writing) does not allow method overloads on the
+constructor, there was no way to automatically derive types. Make a habit of using the `subStore`
+function if you use typescript.
+
+#### Subclassing SubStore
+If you want to create a class and mutation methods for your SubStore, you'll want to create an
+interface for your parent type that requires a minimum interface of the part you deal with. Then
+you create a custom constructor with your accessor or setter/getter.
+```typescript
+interface AboutType {
+  header: string
+}
+interface HasAboutType {
+  about: AboutType
+}
+class AboutStore<ParentType extends HasAboutType> extends SubStore<AboutType, ParentType> {
+  constructor (parentStore: WritableSubject<ParentType>) {
+    super(parentStore, 'about')
+  }
+
+  updateHeader (newHeader: string) {
+    this.update(state => ({ ...state, header: newHeader }))
+  }
+}
+const parentStore = new Store({
+  about: { header: 'About' },
+  events: { header: 'Events' }
+})
+const aboutStore = new AboutStore(parentStore)
+aboutStore.updateHeader('About Us')
+```
+Note the use of `WritableSubject` in the constructor. This is exported from our library, and is
+a generic way of accepting any kind of store - it accepts anything with a `subscribe` and `update`
+method. So you can write a SubStore that accepts default svelte stores as well as one of our stores.
+
+### derivedStore
+`derivedStore` is designed to allow you to compile data from one or more parent stores into another
+read-only store. Each time any parent store changes, we'll run a function to derive a new state from
+the parent state(s). This is extremely similar to svelte's `derived` store, but subscribers will only
+be notified if the derived state has changed (uses a deep-equal instead of svelte's shallow equality).
+```typescript
+const num1Store = new Store(5)
+const num2Store = new Store(7)
+const sumStore = derivedStore([num1Store, num2Store], ([num1, num2]) => num1 + num2)
+// sumStore state is 12
+num1Store.set(3)
+// sumStore state is 10
+```
+If you only use one parent store, it's possible to use a dot-prop string as the getter, basically a
+read-only version of SubStore.
+
+### convertStore
+`convertStore` is provided to add deep equality checks to a svelte store. The state is duplicated into
+one of our stores, but the duplicate is kept in sync with the parent svelte store and vice-versa. You can
+feel free to `set` and `update` the converted store even if some of your code still uses the parent svelte
+store.
+```typescript
+const svelteStore = writable({ putit: 'there' })
+const deepEqualStore = convertStore(svelteStore)
+svelteStore.set({ putit: 'here' })
+// both stores have state { putit: 'here' }
+deepEqualStore.set({ putit: 'there' })
+// both stores are back to { putit: 'there' }
+deepEqualStore.set({ putit: 'there' })
+// no subscribers are notified, because deepEqualStore caught that nothing was updated
+svelteStore.set({ putit: 'there' })
+// svelteStore subscribers are notified, but deepEqualStore subscribers are not
+```

package/package.json

@@ -1,57 +1,35 @@
 {
   "name": "@txstate-mws/svelte-components",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Svelte components that are generically useful.",
+  "scripts": {
+    "dev": "svelte-kit dev",
+    "build": "svelte-kit build",
+    "package": "svelte-kit package",
+    "preview": "svelte-kit preview",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch",
+    "lint": "eslint --ignore-path .gitignore .",
+    "test": "playwright test tests"
+  },
   "dependencies": {
     "@txstate-mws/svelte-store": "^1.0.3",
     "tabbable": "^5.2.1",
     "txstate-utils": "^1.6.0"
   },
   "devDependencies": {
-    "@babel/preset-env": "^7.16.11",
+    "@playwright/test": "^1.18.1",
     "@sveltejs/adapter-auto": "next",
     "@sveltejs/kit": "next",
-    "@testing-library/jest-dom": "^5.16.1",
-    "@testing-library/svelte": "^3.0.3",
-    "@testing-library/user-event": "^13.5.0",
     "@types/tabbable": "^3.1.2",
     "eslint-config-standard-with-typescript": "^21.0.1",
     "eslint-plugin-svelte3": "^3.2.1",
     "svelte": "^3.44.0",
-    "svelte2tsx": "^0.5.1",
     "svelte-check": "^2.2.6",
-    "svelte-jester": "^2.3.1",
     "svelte-preprocess": "^4.9.4",
-    "ts-jest": "^27.1.3",
+    "svelte2tsx": "^0.5.2",
     "tslib": "^2.3.1",
     "typescript": "^4.4.3"
   },
-  "type": "module",
-  "exports": {
-    "./package.json": "./package.json",
-    "./actions/buttonify": "./actions/buttonify.js",
-    "./actions/glue": "./actions/glue.js",
-    "./actions": "./actions/index.js",
-    "./actions/offset": "./actions/offset.js",
-    "./actions/portal": "./actions/portal.js",
-    "./actions/resize": "./actions/resize.js",
-    "./actions/sticky": "./actions/sticky.js",
-    "./actions/stickyfixed": "./actions/stickyfixed.js",
-    "./components/CollapsingTable.svelte": "./components/CollapsingTable.svelte",
-    "./components/ConditionalWrapper.svelte": "./components/ConditionalWrapper.svelte",
-    "./components/FocusLock.svelte": "./components/FocusLock.svelte",
-    "./components/Modal.svelte": "./components/Modal.svelte",
-    "./components/PopupMenu.svelte": "./components/PopupMenu.svelte",
-    "./components/ScreenReaderOnly.svelte": "./components/ScreenReaderOnly.svelte",
-    "./components": "./components/index.js",
-    ".": "./index.js",
-    "./types/CollapsingTable": "./types/CollapsingTable.js",
-    "./types/PopupMenu": "./types/PopupMenu.js",
-    "./types": "./types/index.js",
-    "./util/bodyoffset": "./util/bodyoffset.js",
-    "./util": "./util/index.js",
-    "./util/repositioned": "./util/repositioned.js",
-    "./util/util": "./util/util.js"
-  },
-  "svelte": "./index.js"
-}
+  "type": "module"
+}