├── .editorconfig
├── .github
    └── workflows
    │   ├── main.yml
    │   └── publish.yml
├── .gitignore
├── .prettierrc.json
├── LICENSE
├── README.md
├── docs
    ├── activeElement.md
    ├── bindInput.md
    ├── documentVisibility.md
    ├── elementSize.md
    ├── elementVisibility.md
    ├── head.md
    ├── index.md
    ├── itemSelection.md
    ├── keyBinding.md
    ├── localStorage.md
    ├── markdown.md
    ├── onLongPress.md
    ├── permissions.md
    ├── propertyHistory.md
    ├── sessionStorage.md
    ├── slot.md
    └── windowScroll.md
├── eslint.config.js
├── package-lock.json
├── package.json
├── src
    ├── _internal
    │   ├── elementTracking.ts
    │   └── storage.ts
    ├── controllers
    │   ├── activeElement.ts
    │   ├── documentVisibility.ts
    │   ├── elementSize.ts
    │   ├── elementVisibility.ts
    │   ├── head.ts
    │   ├── itemSelection.ts
    │   ├── keyBinding.ts
    │   ├── localStorage.ts
    │   ├── markdown.ts
    │   ├── permissions.ts
    │   ├── propertyHistory.ts
    │   ├── sessionStorage.ts
    │   ├── slot.ts
    │   └── windowScroll.ts
    ├── directives
    │   ├── bindInput.ts
    │   └── onLongPress.ts
    ├── main.ts
    └── test
    │   ├── controllers
    │       ├── activeElement_test.ts
    │       ├── documentVisibility_test.ts
    │       ├── elementSize_test.ts
    │       ├── elementVisibility_test.ts
    │       ├── head_test.ts
    │       ├── itemSelection_test.ts
    │       ├── keyBinding_test.ts
    │       ├── localStorage_test.ts
    │       ├── markdown_test.ts
    │       ├── permissions_test.ts
    │       ├── propertyHistory_test.ts
    │       ├── sessionStorage_test.ts
    │       ├── slot_test.ts
    │       └── windowScroll_test.ts
    │   ├── directives
    │       ├── bindInput_test.ts
    │       └── onLongPress_test.ts
    │   └── util.ts
├── tsconfig.json
└── web-test-runner.config.mjs


/.editorconfig:
--------------------------------------------------------------------------------
1 | root = true
2 | 
3 | [*]
4 | end_of_line = lf
5 | indent_size = 2
6 | indent_style = space
7 | trim_trailing_whitespace = true
8 | 


--------------------------------------------------------------------------------
/.github/workflows/main.yml:
--------------------------------------------------------------------------------
 1 | name: Build & Test
 2 | 
 3 | on:
 4 |   push:
 5 |     branches: [main]
 6 |   pull_request:
 7 | 
 8 | jobs:
 9 |   test:
10 |     runs-on: ubuntu-22.04
11 |     strategy:
12 |       matrix:
13 |         node-version: [20.x, 22.x, 23.x]
14 |       fail-fast: false
15 |     steps:
16 |       - name: Checkout
17 |         uses: actions/checkout@v4
18 |       - name: Use Node v${{ matrix.node-version }}
19 |         uses: actions/setup-node@v4
20 |         with:
21 |           node-version: ${{ matrix.node-version }}
22 |       - name: Install Dependencies
23 |         run: npm ci
24 |       - name: Lint
25 |         run: npm run lint
26 |       - name: Test
27 |         run: npm run test
28 |       - name: Report Test Coverage
29 |         uses: coverallsapp/github-action@master
30 |         with:
31 |           github-token: ${{ secrets.GITHUB_TOKEN }}
32 | 


--------------------------------------------------------------------------------
/.github/workflows/publish.yml:
--------------------------------------------------------------------------------
 1 | name: Publish Release (npm)
 2 | 
 3 | on:
 4 |   release:
 5 |     types: [published]
 6 | 
 7 | jobs:
 8 |   build:
 9 |     runs-on: ubuntu-22.04
10 |     steps:
11 |       - name: Checkout
12 |         uses: actions/checkout@v4
13 |       - name: Setup Node
14 |         uses: actions/setup-node@v4
15 |         with:
16 |           node-version: 20
17 |       - name: Install Dependencies
18 |         run: npm ci
19 |       - name: Lint
20 |         run: npm run lint
21 |       - name: Test
22 |         run: npm test
23 | 
24 |   publish-npm:
25 |     needs: build
26 |     runs-on: ubuntu-latest
27 |     permissions:
28 |       id-token: write
29 |     steps:
30 |       - uses: actions/checkout@v4
31 |       - uses: actions/setup-node@v4
32 |         with:
33 |           node-version: 22.x
34 |           registry-url: 'https://registry.npmjs.org'
35 |           cache: 'npm'
36 |       - run: npm ci
37 |       - run: npm run build
38 |       - run: npm version ${TAG_NAME} --git-tag-version=false
39 |         env:
40 |           TAG_NAME: ${{ github.ref_name }}
41 |       - run: npm publish --provenance --access public --tag next
42 |         if: "github.event.release.prerelease"
43 |         env:
44 |           NODE_AUTH_TOKEN: ${{ secrets.npm_token }}
45 |       - run: npm publish --provenance --access public
46 |         if: "!github.event.release.prerelease"
47 |         env:
48 |           NODE_AUTH_TOKEN: ${{ secrets.npm_token }}
49 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | /lib
3 | *.swp
4 | /coverage
5 | 


--------------------------------------------------------------------------------
/.prettierrc.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "bracketSpacing": false,
 3 |   "printWidth": 80,
 4 |   "semi": true,
 5 |   "singleQuote": true,
 6 |   "tabWidth": 2,
 7 |   "trailingComma": "none",
 8 |   "useTabs": false,
 9 |   "arrowParens": "always",
10 |   "embeddedLanguageFormatting": "off"
11 | }
12 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2023 James Garbutt
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # relit
 2 | 
 3 | relit (reactive lit) is a collection of utilities to provide various features
 4 | as reactive state to [lit](https://lit.dev) components.
 5 | 
 6 | DOM state, web APIs, property history and much more.
 7 | 
 8 | ## Install
 9 | 
10 | To install `relit`, simply add it as a dependency to your lit project:
11 | 
12 | ```sh
13 | npm i -S relit
14 | ```
15 | 
16 | ## Usage
17 | 
18 | For usage, see the [docs](./docs/index.md) of each available utility.
19 | 
20 | ## License
21 | 
22 | MIT
23 | 


--------------------------------------------------------------------------------
/docs/activeElement.md:
--------------------------------------------------------------------------------
 1 | # activeElement
 2 | 
 3 | `activeElement` allows you to observe the current active element of a document.
 4 | 
 5 | ## Usage
 6 | 
 7 | ```ts
 8 | class MyElement extends LitElement {
 9 |   constructor() {
10 |     super();
11 | 
12 |     this._activeElementCtrl = new ActiveElementController(this);
13 |   }
14 | 
15 |   render() {
16 |     return html`
17 |       Active element is: ${this._activeElementCtrl.activeElement?.nodeName}.
18 |     `;
19 |   }
20 | }
21 | ```
22 | 
23 | ## Options
24 | 
25 | An optional `doc` can be passed when constructing this controller, such that
26 | you can observe the `activeElement` of a shadow root or a different document:
27 | 
28 | ```ts
29 | this._activeElementCtrl = new ActiveElementController(this, this.shadowRoot);
30 | ```
31 | 
32 | Each shadow root has its own active element, while the parent document will
33 | only see as far as the shadow boundary (i.e. the host element) in terms of
34 | its own `activeElement`.
35 | 
36 | You can read more about this [here](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/activeElement).
37 | 


--------------------------------------------------------------------------------
/docs/bindInput.md:
--------------------------------------------------------------------------------
 1 | # bindInput
 2 | 
 3 | `bindInput` allows you to automatically bind a form input/control to a given
 4 | property (i.e. two-way binding).
 5 | 
 6 | ## Usage
 7 | 
 8 | ```ts
 9 | class MyElement extends LitElement {
10 |   @property({type: String})
11 |   public name: string = 'Bob';
12 | 
13 |   render() {
14 |     return html`
15 |       <label>
16 |         Name:
17 |         <input type="text" ${bindInput(this, 'name')}>
18 |       </label>
19 |     `;
20 |   }
21 | }
22 | ```
23 | 
24 | This will automatically two-way bind the `input` element and the `name`
25 | property.
26 | 
27 | The parameters (`bindInput(host, property)`) are as follows:
28 | 
29 | - `host` - any object which has the specified `property`
30 | - `property` - the name of the property on `host` to bind
31 | 
32 | ### By attribute/property
33 | 
34 | You may also use this directive with an attribute or property binding:
35 | 
36 | ```ts
37 |     return html`
38 |       <label>
39 |         Name:
40 |         <input type="text" .value=${bindInput(this, 'name')}>
41 |       </label>
42 |     `;
43 | ```
44 | 
45 | This may help with SSR, and will work the same way as the element binding
46 | usage.
47 | 
48 | ## Supported elements
49 | 
50 | The following elements are supported by this directive:
51 | 
52 | - `input`
53 | - `select`
54 | - `textarea`
55 | - Compatible elements
56 | 
57 | ### Events
58 | 
59 | By default, we listen for the `change` event and the `input` event.
60 | 
61 | ### `<input type="checkbox">`
62 | 
63 | Checkbox inputs will result in a boolean value:
64 | 
65 | ```ts
66 |   return html`
67 |     <input type="checkbox" ${bindInput(this, 'isEnabled')}>
68 |   `;
69 | ```
70 | 
71 | In this example, `this.isEnabled` will be `true` or `false` depending on the
72 | checked state of the input.
73 | 
74 | ### `<select>`
75 | 
76 | Select element bindings differ depending on if the select is `multiple` or not.
77 | 
78 | With `<select multiple>`, the value will be an array of the selected values.
79 | 
80 | With a regular `<select>`, the value will be the selected value.
81 | 
82 | ### Compatible elements
83 | 
84 | Any element which implements the following will be supported:
85 | 
86 | - Emits `change` events and/or `input` events
87 | - Has a `value` property
88 | 
89 | ## Options
90 | 
91 | N/A
92 | 


--------------------------------------------------------------------------------
/docs/documentVisibility.md:
--------------------------------------------------------------------------------
 1 | # documentVisibility
 2 | 
 3 | `documentVisibility` allows you to observe the visibility state of a document.
 4 | 
 5 | ## Usage
 6 | 
 7 | ```ts
 8 | class MyElement extends LitElement {
 9 |   constructor() {
10 |     super();
11 | 
12 |     this._documentVisibilityCtrl = new DocumentVisibilityController(this);
13 |   }
14 | 
15 |   render() {
16 |     const visibility = this._elementVisibilityCtrl.visible ? 'visible' : 'hidden';
17 | 
18 |     return html`
19 |       Document is currently ${visibility}.
20 |     `;
21 |   }
22 | }
23 | ```
24 | 
25 | The `visible` property will be `true` or `false` depending on if the document
26 | is currently visible or not.
27 | 
28 | ## Options
29 | 
30 | N/A
31 | 


--------------------------------------------------------------------------------
/docs/elementSize.md:
--------------------------------------------------------------------------------
 1 | # elementSize
 2 | 
 3 | `elementSize` allows you to observe the size of a given element (width and
 4 | height).
 5 | 
 6 | ## Usage
 7 | 
 8 | ```ts
 9 | class MyElement extends LitElement {
10 |   constructor() {
11 |     super();
12 | 
13 |     this._elementSizeCtrl = new ElementSizeController(this);
14 |   }
15 | 
16 |   render() {
17 |     const {width, height} = this._elementSizeCtrl.size;
18 |     return html`
19 |       This element is currently ${width} by ${height}.
20 |     `;
21 |   }
22 | }
23 | ```
24 | 
25 | As defined [here](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilityState).
26 | 
27 | ## Options
28 | 
29 | When constructing this controller, you can specify the following as additional
30 | parameters:
31 | 
32 | - `type`
33 | - `ref`
34 | 
35 | ### `type`
36 | 
37 | The type can be used to specify what kind of size you want to observe. For
38 | example, the content-box dimensions or the border-box dimensions.
39 | 
40 | You can read more about those types [here](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing).
41 | 
42 | For example:
43 | 
44 | ```ts
45 | new ElementSizeController(this, 'border');
46 | ```
47 | 
48 | ### `ref`
49 | 
50 | You can also pass a [`ref`](https://lit.dev/docs/templates/directives/#ref),
51 | such that the referenced element will have its size observed rather than the
52 | host element.
53 | 
54 | You should create such a ref via the `createRef` helper and use the `ref`
55 | directive to populate it.
56 | 
57 | For example:
58 | 
59 | ```ts
60 | class MyElement extends LitElement {
61 |   constructor() {
62 |     super();
63 |     this._myRef = createRef();
64 |     this._elementSizeCtrl = new ElementSizeController(this, 'content', myRef);
65 |   }
66 | 
67 |   render() {
68 |     const {width, height} = this._elementSizeCtrl.size;
69 |     return html`
70 |       <p>The element below is currently ${width} by ${height}.</p>
71 | 
72 |       <div ${ref(this._myRef)}>
73 |         Some element which changes size
74 |       </div>
75 |     `;
76 |   }
77 | }
78 | ```
79 | 


--------------------------------------------------------------------------------
/docs/elementVisibility.md:
--------------------------------------------------------------------------------
 1 | # elementVisibility
 2 | 
 3 | `elementVisibility` allows you to observe the current visibility of a particular
 4 | element within the viewport. That is, when the element is outside the viewport,
 5 | the visibility will be `false`.
 6 | 
 7 | ## Usage
 8 | 
 9 | ```ts
10 | class MyElement extends LitElement {
11 |   constructor() {
12 |     super();
13 | 
14 |     this._elementVisibilityCtrl = new ElementVisibilityController(this);
15 |   }
16 | 
17 |   render() {
18 |     const visibility = this._elementVisibilityCtrl.visible ? 'visible' : 'hidden';
19 | 
20 |     return html`
21 |       This element is currently ${visibility}.
22 |     `;
23 |   }
24 | }
25 | ```
26 | 
27 | ## Options
28 | 
29 | When constructing this controller, you can specify the following as additional
30 | parameters:
31 | 
32 | - `ref`
33 | 
34 | ### `ref`
35 | 
36 | You can pass a [`ref`](https://lit.dev/docs/templates/directives/#ref),
37 | such that the referenced element will have its visibility observed rather than
38 | the host element.
39 | 
40 | You should create such a ref via the `createRef` helper and use the `ref`
41 | directive to populate it.
42 | 
43 | For example:
44 | 
45 | ```ts
46 | class MyElement extends LitElement {
47 |   constructor() {
48 |     super();
49 |     this._myRef = createRef();
50 |     this._elementVisibilityCtrl = new ElementVisibilityController(
51 |       this,
52 |       this._myRef
53 |     );
54 |   }
55 | 
56 |   render() {
57 |     const visibility = this._elementVisibilityCtrl.visible ? 'visible' : 'hidden';
58 | 
59 |     return html`
60 |       <p>The element below is currently ${visibility}.</p>
61 | 
62 |       <div ${ref(this._myRef)}>
63 |         This element is being observed.
64 |       </div>
65 |     `;
66 |   }
67 | }
68 | ```
69 | 


--------------------------------------------------------------------------------
/docs/head.md:
--------------------------------------------------------------------------------
  1 | # head
  2 | 
  3 | `head` allows you to manage the `<head>` tag and various document metadata.
  4 | 
  5 | ## Usage
  6 | 
  7 | ```ts
  8 | class MyElement extends LitElement {
  9 |   constructor() {
 10 |     super();
 11 | 
 12 |     this._headCtrl = new HeadController(this);
 13 |   }
 14 | 
 15 |   onClickOfSomething() {
 16 |     this._headCtrl.setTitle('Example Page Title');
 17 | 
 18 |     this._headCtrl.update(html`
 19 |       <meta name="foo" content="some content">
 20 |       <meta name="bar" content="some content">
 21 |     `;
 22 |   }
 23 | }
 24 | ```
 25 | 
 26 | ## Options
 27 | 
 28 | An optional document argument can be passed to this controller if you wish
 29 | to manage a document other than the current one:
 30 | 
 31 | ```ts
 32 | new HeadController(this, doc);
 33 | ```
 34 | 
 35 | ## Properties
 36 | 
 37 | ### `titleTemplate`
 38 | 
 39 | Setting `titleTemplate` will apply a template any time the controller is used
 40 | to set the page title.
 41 | 
 42 | For example:
 43 | 
 44 | ```ts
 45 | this._headCtrl.titleTemplate = '%s - My Website';
 46 | 
 47 | this._headCtrl.setTitle('Some Page'); // Some Page - My Website
 48 | ```
 49 | 
 50 | ### `defaultTitle`
 51 | 
 52 | This will set the default title to use when no other has been passed.
 53 | 
 54 | For example, when the element is first attached, it will set the page
 55 | title to this default.
 56 | 
 57 | Similarly, if you used `update` to render a `<title>` and since removed it,
 58 | the default will be used instead.
 59 | 
 60 | ## Methods
 61 | 
 62 | ### `update`
 63 | 
 64 | Allows you to render tags to the `<head>` of the document.
 65 | 
 66 | For example:
 67 | 
 68 | ```ts
 69 | this._headCtrl.update(html`
 70 |   <meta name="foo" content="foo">
 71 | 
 72 |   <meta name="bar" content="bar">
 73 | 
 74 |   <title>Some Title</title>
 75 | 
 76 |   <base href="/">
 77 | `);
 78 | ```
 79 | 
 80 | If you call this multiple times, **all previously rendered elements will be
 81 | replaced**.
 82 | 
 83 | 
 84 | The following elements are supported:
 85 | 
 86 | - `<title>`
 87 | - `<base>`
 88 | - `<meta>`
 89 | - `<link>`
 90 | - `<script>`
 91 | - `<noscript>`
 92 | - `<style>`
 93 | 
 94 | Note that `title` and `base` have special behaviour, in that they will replace
 95 | any existing equivalent head tag whether rendered by this controller or not.
 96 | 
 97 | ### `setTitle`
 98 | 
 99 | Sets the page title:
100 | 
101 | ```ts
102 | this._headCtrl.setTitle('Page Title');
103 | ```
104 | 
105 | ### `updateBodyAttr`
106 | 
107 | Updates the `<body>` tag of the document with a specified set of attributes.
108 | 
109 | You may pass `null` as an attribute value to forcefully remove it.
110 | 
111 | For example:
112 | 
113 | ```ts
114 | this._headCtrl.updateBodyAttr({
115 |   'data-foo': 'foo',
116 |   'data-bar': 'bar'
117 | });
118 | 
119 | // <body data-foo="foo" data-bar="bar">
120 | 
121 | this._headCtrl.updateBodyAttr({
122 |   'data-foo': 'foo',
123 |   'data-bar': null
124 | });
125 | 
126 | // <body data-foo="foo">
127 | ```
128 | 
129 | **Keep in mind, all attributes are _additive_**. This means if you call the
130 | method multiple times with different attributes, the tag will accumulate all of
131 | them.
132 | 
133 | ### `updateHtmlAttr`
134 | 
135 | Updates the `<html>` tag of the document with a specified set of attributes.
136 | 
137 | 
138 | You may pass `null` as an attribute value to forcefully remove it.
139 | 
140 | For example:
141 | 
142 | ```ts
143 | this._headCtrl.updateHtmlAttr({
144 |   'data-foo': 'foo',
145 |   'data-bar': 'bar'
146 | });
147 | 
148 | // <html data-foo="foo" data-bar="bar">
149 | 
150 | this._headCtrl.updateHtmlAttr({
151 |   'data-foo': 'foo',
152 |   'data-bar': null
153 | });
154 | 
155 | // <html data-foo="foo">
156 | ```
157 | 
158 | ### `removeRenderedElements`
159 | 
160 | Removes all elements this controller has rendered via `update`.
161 | 


--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
 1 | # relit - list of utilities
 2 | 
 3 | The following is the full list of available utilities:
 4 | 
 5 | - [activeElement](./activeElement.md) - observable [document.activeElement](https://developer.mozilla.org/en-US/docs/Web/API/Document/activeElement)
 6 | - [bindInput](./bindInput.md) - two-way bindings of form controls/inputs
 7 | - [documentVisibility](./documentVisibility.md) - observable [document.visibilityState](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilityState)
 8 | - [elementSize](./elementSize.md) - element width and height
 9 | - [elementVisibility](./elementVisibility.md) - element visibility
10 | - [head](./head.md) - `<head>` tag management
11 | - [itemSelection](./itemSelection.md) - manages selection within an array of items
12 | - [keyBinding](./keyBinding.md) - key bindings (shortcuts) manager
13 | - [localStorage](./localStorage.md) - items in [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
14 | - [markdown](./markdown.md) - markdown processing via [marked](https://github.com/markedjs/marked)
15 | - [onLongPress](./onLongPress.md) - fire callback on long press
16 | - [permissions](./permissions.md) - track the state of a browser [permission](https://developer.mozilla.org/en-US/docs/Web/API/Permissions/query)
17 | - [propertyHistory](./propertyHistory.md) - track the history of a property with undo/redo
18 | - [sessionStorage](./sessionStorage.md) - items in [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
19 | - [slot](./slot.md) - track slotted elements
20 | - [windowScroll](./windowScroll.md) - track the window scroll offset
21 | 


--------------------------------------------------------------------------------
/docs/itemSelection.md:
--------------------------------------------------------------------------------
  1 | # itemSelection
  2 | 
  3 | `itemSelection` allows you to navigate around an array of items (via methods
  4 | like `next()` and `prev()`), and react to the selection having changed.
  5 | 
  6 | ## Usage
  7 | 
  8 | ```ts
  9 | class MyElement extends LitElement {
 10 |   @state()
 11 |   public items: string[] = ['one', 'two', 'three'];
 12 | 
 13 |   constructor() {
 14 |     super();
 15 | 
 16 |     this._itemSelectionCtrl = new ItemSelectionController(
 17 |       this,
 18 |       this.items
 19 |     );
 20 |   }
 21 | 
 22 |   render() {
 23 |     const {selectedItems} = this._itemSelectionCtrl;
 24 | 
 25 |     return html`
 26 |       Selected strings are: ${selectedItems}.
 27 | 
 28 |       <button
 29 |         @click=${() => this._itemSelectionCtrl.next()}>
 30 |         Next item
 31 |       </button>
 32 | 
 33 |       <button
 34 |         @click=${() => this._itemSelectionCtrl.prev()}>
 35 |         Previous item
 36 |       </button>
 37 |     `;
 38 |   }
 39 | }
 40 | ```
 41 | 
 42 | In this example, we would initially render nothing (no selection) and would
 43 | use single-selection mode (the default).
 44 | 
 45 | On clicking `Next item`, we would select the first item (`"one"`).
 46 | 
 47 | If we continued to click `Next item`, we would select the second item (`"two"`).
 48 | 
 49 | ## Options
 50 | 
 51 | This controller accepts an optional `options` parameter, which is an object
 52 | used to configure various features.
 53 | 
 54 | ### `options.multiSelect`
 55 | 
 56 | If you set this to `true`, multiple items may be selected.
 57 | 
 58 | For example, you may call `selectByIndex(0)` followed by `selectByIndex(1)` and
 59 | both will remain marked as selected.
 60 | 
 61 | This also means you can no longer use the following methods (as they will
 62 | only function with a single selection):
 63 | 
 64 | - `next()`
 65 | - `prev()`
 66 | - `selectByOffset()`
 67 | 
 68 | ### `options.defaultSelectedIndices`
 69 | 
 70 | You can specify the item indices to select by default using this option.
 71 | 
 72 | For example:
 73 | 
 74 | ```ts
 75 | const items = ['a', 'b', 'c'];
 76 | 
 77 | const ctrl = new ItemSelectionController(
 78 |   this,
 79 |   items,
 80 |   { defaultSelectedIndices: [1] }
 81 | );
 82 | 
 83 | // ctrl will default to `b` being selected as it is at index 1.
 84 | ```
 85 | 
 86 | ### `options.defaultSelection`
 87 | 
 88 | You can specify the items to select by default using this option.
 89 | 
 90 | For example:
 91 | 
 92 | ```ts
 93 | const items = ['a', 'b', 'c'];
 94 | 
 95 | const ctrl = new ItemSelectionController(
 96 |   this,
 97 |   items,
 98 |   { defaultSelection: ['b'] }
 99 | );
100 | 
101 | // ctrl will default to `b` being selected
102 | ```
103 | 
104 | ## Methods
105 | 
106 | ### `next()`
107 | 
108 | In single-selection mode, moves the selection to the next item.
109 | 
110 | If there is no next item, it will remain at the last item.
111 | 
112 | ### `prev()`
113 | 
114 | In single-selection mode, moves the selection to the previous item.
115 | 
116 | If there is no previous item, it will remain at the first item.
117 | 
118 | ### `selectByOffset(offset)`
119 | 
120 | In single-selection mode, moves the selection by the specified offset.
121 | 
122 | For example, `selectByOffset(-2)` will select the item positioned two places
123 | before the current selection.
124 | 
125 | If there is no item at such an offset, the item at the boundary will be
126 | selected (the first or last item, depending on if you moved positively
127 | or negatively).
128 | 
129 | ### `selectByIndex(index)`
130 | 
131 | Selects the item at the given index.
132 | 
133 | ### `select(item)`
134 | 
135 | Selects the given item.
136 | 
137 | ### `deselectAll()`
138 | 
139 | Deselects all items.
140 | 
141 | ### `selectAll()`
142 | 
143 | Selects all items.
144 | 
145 | ### `deselect(item)`
146 | 
147 | Deselects the given item.
148 | 
149 | ### `deselectByIndex(index)`
150 | 
151 | Deselects the item at the given index.
152 | 
153 | ### `toggleByIndex(index[, selected])`
154 | 
155 | Toggles the item at the given index.
156 | 
157 | For example, if the item at `2` is selected, `toggleByIndex(2)` will deselect
158 | it.
159 | 
160 | You can optionally also specify the selection state to force a select or
161 | deselect (e.g. `toggleByIndex(2, true)` to force `2` to be selected).
162 | 
163 | ### `toggle(item[, selected])`
164 | 
165 | Toggles the given item.
166 | 
167 | As with `toggleByIndex`, you can optionally specify the selection state to
168 | force a select or a deselect.
169 | 


--------------------------------------------------------------------------------
/docs/keyBinding.md:
--------------------------------------------------------------------------------
  1 | # keyBinding
  2 | 
  3 | `keyBinding` allows you to bind actions to particular key combinations on
  4 | either the host element or a referenced child element.
  5 | 
  6 | ## Usage
  7 | 
  8 | ```ts
  9 | class MyElement extends LitElement {
 10 |   constructor() {
 11 |     super();
 12 | 
 13 |     this._keyCtrl = new KeyBindingController(this);
 14 |     this._keyCtrl.bindKey('x', this._onXPressed);
 15 |   }
 16 | 
 17 |   render() {
 18 |     return html`
 19 |       You can press the X key in me to make something happen!
 20 |     `;
 21 |   }
 22 | }
 23 | ```
 24 | 
 25 | ## Options
 26 | 
 27 | When constructing this controller, you can specify the following as additional
 28 | parameters:
 29 | 
 30 | - `ref`
 31 | - `options`
 32 | 
 33 | ### `ref`
 34 | 
 35 | You can pass a [`ref`](https://lit.dev/docs/templates/directives/#ref),
 36 | such that the referenced element will observe its key presses rather than the
 37 | host element.
 38 | 
 39 | You should create such a ref via the `createRef` helper and use the `ref`
 40 | directive to populate it.
 41 | 
 42 | For example:
 43 | 
 44 | ```ts
 45 | class MyElement extends LitElement {
 46 |   constructor() {
 47 |     super();
 48 |     this._myRef = createRef();
 49 |     this._keyCtrl = new KeyBindingController(this, this._myRef);
 50 |   }
 51 | 
 52 |   render() {
 53 |     return html`
 54 |       <div ${ref(this._myRef)}>
 55 |         This div has key bindings!
 56 |       </div>
 57 |     `;
 58 |   }
 59 | }
 60 | ```
 61 | 
 62 | ### `options`
 63 | 
 64 | The options object allows you specify various global options for the binding
 65 | manager.
 66 | 
 67 | #### `options.ignoredElements`
 68 | 
 69 | Default: `['textarea', 'input', 'select']`
 70 | 
 71 | This option allows you to specify a set of elements which the manager will
 72 | ignore key presses from.
 73 | 
 74 | For example, by default if you press keys in an `<input>`, they will not be
 75 | handled by the manager.
 76 | 
 77 | The values you specify here are CSS selectors, allowing you to also do
 78 | something like the following:
 79 | 
 80 | ```ts
 81 | {
 82 |   ignoredElements: ['.foo']
 83 | }
 84 | ```
 85 | 
 86 | ## Methods
 87 | 
 88 | ### `bindKey(key, fn[, options])`
 89 | 
 90 | Binds a function to be called any time `key` is pressed.
 91 | 
 92 | By default, this binds to the `keyup` event which means the function will only
 93 | be called once the user releases the key.
 94 | 
 95 | You can also pass an `options` object to customise this behaviour.
 96 | 
 97 | #### `options.triggers`
 98 | 
 99 | You may specify a set of `triggers` to choose when your function is called
100 | during a key press.
101 | 
102 | Supported triggers are:
103 | 
104 | - `keyup` - when the user has pressed and released a key
105 | - `keydown` - when the user has pressed a key (**repeated while the user holds
106 | the key down**)
107 | - `firstKeyDown` - when the user has initially pressed a key
108 | 
109 | For example:
110 | 
111 | ```ts
112 | // calls `fn` as the user holds the `x` key
113 | keybindings.bindKey('x', fn, {triggers: ['keydown']});
114 | ```
115 | 
116 | ### `bindFocus(key, ref)`
117 | 
118 | Binds a key to focusing the specified element (by ref).
119 | 
120 | For example:
121 | 
122 | ```ts
123 | // Focus search input when user presses `/` key
124 | keybindings.bindFocus('/', searchInputRef);
125 | ```
126 | 
127 | ### `bindPush(key, fn)`
128 | 
129 | Binds a function to be called when a key is initially pressed, and when it is
130 | later released.
131 | 


--------------------------------------------------------------------------------
/docs/localStorage.md:
--------------------------------------------------------------------------------
 1 | # localStorage
 2 | 
 3 | `localStorage` allows you to observe the value of a particular key in local
 4 | storage.
 5 | 
 6 | ## Usage
 7 | 
 8 | ```ts
 9 | class MyElement extends LitElement {
10 |   constructor() {
11 |     super();
12 | 
13 |     this._localStorageCtrl = new LocalStorageController(this, 'someKey');
14 |   }
15 | 
16 |   render() {
17 |     const val = JSON.stringify(this._localStorageCtrl.value);
18 | 
19 |     return html`
20 |       someKey currently has the value: ${val}.
21 |     `;
22 |   }
23 | }
24 | ```
25 | 
26 | ## Options
27 | 
28 | The following options exist:
29 | 
30 | - `defaultValue`
31 | 
32 | ### `defaultValue`
33 | 
34 | This parameter can be passed to specify what the value should default to if it
35 | is not already set.
36 | 
37 | Specifying this will result in the default being stored in local storage if the
38 | key doesn't already exist.
39 | 
40 | For example:
41 | 
42 | ```ts
43 | new LocalStorageController(
44 |   this,
45 |   'someKey',
46 |   ['some', 'default']
47 | );
48 | ```
49 | 


--------------------------------------------------------------------------------
/docs/markdown.md:
--------------------------------------------------------------------------------
 1 | # markdown
 2 | 
 3 | `markdown` allows you to process markdown into HTML and render the result.
 4 | 
 5 | ## Usage
 6 | 
 7 | ```ts
 8 | class MyElement extends LitElement {
 9 |   @property({type: String})
10 |   prop = `
11 |     # Header
12 | 
13 |     Some text.
14 |   `;
15 | 
16 |   constructor() {
17 |     super();
18 | 
19 |     this._markdownCtrl = new MarkdownController(this, {
20 |       property: 'prop'
21 |     });
22 |   }
23 | 
24 |   render() {
25 |     return html`
26 |       Rendered markdown:
27 | 
28 |       ${this._markdownCtrl.value}
29 |     `;
30 |   }
31 | }
32 | ```
33 | 
34 | ## Options
35 | 
36 | An options object may be passed to tailor how the markdown is generated.
37 | 
38 | ### `options.property`
39 | 
40 | You may set `options.property` to the name of a
41 | [reactive property](https://lit.dev/docs/components/properties/), such that
42 | every time it updates, the value will be parsed as markdown.
43 | 
44 | This may be easier than calling `setValue` manually each time you want to
45 | update the value.
46 | 
47 | For example:
48 | 
49 | ```ts
50 | this._markdownCtrl = new MarkdownController(this, {
51 |   property: 'propertyOfThis'
52 | });
53 | ```
54 | 
55 | In this example, every time `this.propertyOfThis` is changed, it will be parsed
56 | as markdown and its rendered HTML placed in `this._markdownCtrl.value`.
57 | 
58 | ### `options.markedOptions`
59 | 
60 | Under the hood, the markdown controller uses
61 | [marked](https://github.com/markedjs/marked) to parse the markdown.
62 | 
63 | You may specify custom options for marked by passing `markedOptions`:
64 | 
65 | ```ts
66 | this._markdownCtrl = new MarkdownController(this, {
67 |   markedOptions: {
68 |     gfm: true
69 |   }
70 | });
71 | ```
72 | 
73 | ## Methods
74 | 
75 | ### `setValue(markdown)`
76 | 
77 | If you want to explicitly set the markdown value to be rendered, you can call
78 | this method.
79 | 
80 | It is likely simpler to use the `options.property` option if your markdown
81 | exists in a reactive property. However, there are still uses for setting the
82 | value directly.
83 | 
84 | For example:
85 | 
86 | ```ts
87 | this._markdownCtrl.setValue(`
88 |   # heading
89 | 
90 |   Some markdown text.
91 | `);
92 | ```
93 | 


--------------------------------------------------------------------------------
/docs/onLongPress.md:
--------------------------------------------------------------------------------
 1 | # onLongPress
 2 | 
 3 | `onLongPress` allows you to bind a callback to a long press occurring (i.e.
 4 | a pointer being held down for a specified amount of time).
 5 | 
 6 | ## Usage
 7 | 
 8 | ```ts
 9 | class MyElement extends LitElement {
10 |   render() {
11 |     return html`
12 |       <div ${onLongPress(this._onLongPress)}>
13 |         Long press me!
14 |       </div>
15 |     `;
16 |   }
17 | }
18 | ```
19 | 
20 | This will call the `_onLongPress` method when the user holds their pointer
21 | down for 1 second (the default).
22 | 
23 | The parameters (`onLongPress(fn, time)`) are as follows:
24 | 
25 | - `fn` - a function to call when the pointer has been held long enough
26 | - `time` - the time in milliseconds to consider a press being 'long'
27 | 
28 | ## Options
29 | 
30 | N/A
31 | 


--------------------------------------------------------------------------------
/docs/permissions.md:
--------------------------------------------------------------------------------
 1 | # permissions
 2 | 
 3 | `permissions` allows you to observe the state of a given browser permission.
 4 | 
 5 | For example, you may wish to observe the state of the `geolocation` permission
 6 | and know when it becomes `granted`.
 7 | 
 8 | ## Usage
 9 | 
10 | ```ts
11 | class MyElement extends LitElement {
12 |   constructor() {
13 |     super();
14 | 
15 |     this._permissionsCtrl = new PermissionsController(this, 'geolocation');
16 |   }
17 | 
18 |   render() {
19 |     return html`
20 |       Geolocation permission is ${this._permissionsCtrl.state}
21 |     `;
22 |   }
23 | }
24 | ```
25 | 
26 | The required argument is a [permission name](https://developer.mozilla.org/en-US/docs/Web/API/Permissions/query#name)
27 | which varies across browsers in some cases.
28 | 
29 | The controller will expose a `state` property which is either a valid
30 | [PermissionState](https://developer.mozilla.org/en-US/docs/Web/API/PermissionStatus/state)
31 | or the string `pending`.
32 | 
33 | Initially, while querying the browser for a state, the state will be set to
34 | `pending`.
35 | 
36 | ## Options
37 | 
38 | N/A
39 | 


--------------------------------------------------------------------------------
/docs/propertyHistory.md:
--------------------------------------------------------------------------------
 1 | # propertyHistory
 2 | 
 3 | `propertyHistory` allows you to observe when a property of your element was last
 4 | changed. It also allows you to undo/redo changes to the property.
 5 | 
 6 | ## Usage
 7 | 
 8 | ```ts
 9 | class MyElement extends LitElement {
10 |   @property({type: String})
11 |   public someProp = 'foo';
12 | 
13 |   constructor() {
14 |     super();
15 | 
16 |     this._propHistoryCtrl = new PropertyHistoryController(
17 |       this,
18 |       'someProp'
19 |     );
20 |   }
21 | 
22 |   render() {
23 |     return html`
24 |       someProp was last changed at ${this._propHistoryCtrl.lastChanged}.
25 |     `;
26 |   }
27 | }
28 | ```
29 | 
30 | ## Options
31 | 
32 | N/A
33 | 
34 | ## Methods
35 | 
36 | There are two methods available:
37 | 
38 | - `undo`
39 | - `redo`
40 | 
41 | There's a maximum of 4 versions of the property's value kept in memory. This
42 | means you can only undo a maximum of 4 times, or if you already did that, you
43 | can only redo a maximum of 4 times.
44 | 
45 | ### `undo()`
46 | 
47 | Calling this will revert the property to its previous value.
48 | 
49 | ### `redo()`
50 | 
51 | Calling this will restore a value you previous reverted.
52 | 


--------------------------------------------------------------------------------
/docs/sessionStorage.md:
--------------------------------------------------------------------------------
 1 | # sessionStorage
 2 | 
 3 | `sessionStorage` allows you to observe the value of a particular key in session
 4 | storage.
 5 | 
 6 | ## Usage
 7 | 
 8 | ```ts
 9 | class MyElement extends LitElement {
10 |   constructor() {
11 |     super();
12 | 
13 |     this._sessionStorageCtrl = new SessionStorageController(this, 'someKey');
14 |   }
15 | 
16 |   render() {
17 |     const val = JSON.stringify(this._sessionStorageCtrl.value);
18 | 
19 |     return html`
20 |       someKey currently has the value: ${val}.
21 |     `;
22 |   }
23 | }
24 | ```
25 | 
26 | ## Options
27 | 
28 | The following options exist:
29 | 
30 | - `defaultValue`
31 | 
32 | ### `defaultValue`
33 | 
34 | This parameter can be passed to specify what the value should default to if it
35 | is not already set.
36 | 
37 | Specifying this will result in the default being stored in session storage if
38 | the key doesn't already exist.
39 | 
40 | For example:
41 | 
42 | ```ts
43 | new SessionStorageController(
44 |   this,
45 |   'someKey',
46 |   ['some', 'default']
47 | );
48 | ```
49 | 


--------------------------------------------------------------------------------
/docs/slot.md:
--------------------------------------------------------------------------------
 1 | # slot
 2 | 
 3 | `slot` allows you to react to changes in your [slotted](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot)
 4 | elements.
 5 | 
 6 | For example, if you'd like to observe when a particular type of node is
 7 | slotted into your element.
 8 | 
 9 | ## Usage
10 | 
11 | ```ts
12 | class MyElement extends LitElement {
13 |   constructor() {
14 |     super();
15 | 
16 |     this._slotCtrl = new SlotController(this);
17 | 
18 |     this._slotCtrl.addListener('[default]', '*', (node) => {
19 |       // I am called every time a new node enters the default slot
20 |     });
21 |   }
22 | 
23 |   render() {
24 |     return html`
25 |       <slot></slot>
26 |     `;
27 |   }
28 | }
29 | ```
30 | 
31 | ## Options
32 | 
33 | N/A
34 | 
35 | ## Methods
36 | 
37 | ### `addListener(slot, selector, callback)`
38 | 
39 | This adds a listener to the controller which will be called any time an element
40 | is slotted into the referenced slot and matches the `selector`.
41 | 
42 | - `slot` may be the name of a slot, or a `Ref` of a slot element
43 | - `selector` must be a CSS selector
44 | - `callback` is a function called when matching elements are slotted
45 | 
46 | In both `slot` and `selector`, you may use `*` to specify "all slots" or
47 | "all elements".
48 | 
49 | You may also use `[default]` to reference the default slot.
50 | 
51 | For example:
52 | 
53 | ```ts
54 | ctrl.addListener('*', '*', (node) => {
55 |   // I am called when any element is slotted into any slot
56 | });
57 | 
58 | ctrl.addListener('[default]', '*', (node) => {
59 |   // I am called when any element is slotted into the default slot
60 | });
61 | 
62 | ctrl.addListener('myslot', '*', (node) => {
63 |   // I am called when any element is slotted into a slot with the name "myslot"
64 | });
65 | 
66 | ctrl.addListener('[default]', 'span', (node) => {
67 |   // I am called when a <span> is slotted into the default slot
68 | });
69 | ```
70 | 
71 | ### `has(slot[, selector, options])`
72 | 
73 | This can be used to determine if the current host element has slotted elements
74 | in a given slot.
75 | 
76 | A selector may also be specified to narrow the selection.
77 | 
78 | For example:
79 | 
80 | ```ts
81 | // true if the default slot has elements
82 | ctrl.has('[default]');
83 | 
84 | // true if any slots have slotted elements
85 | ctrl.has('*');
86 | 
87 | // true if the <slot> named "foo" has slotted elements
88 | ctrl.has('foo');
89 | 
90 | // true if a `<span>` has been slotted into the default slot
91 | ctrl.has('[default]', 'span');
92 | ```
93 | 
94 | You may also specify `options` to further customise the behaviour:
95 | 
96 | - `options.flatten` - see [here](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements#flatten)
97 | 


--------------------------------------------------------------------------------
/docs/windowScroll.md:
--------------------------------------------------------------------------------
 1 | # windowScroll
 2 | 
 3 | `windowScroll` allows you to observe the current scroll offset of the window.
 4 | 
 5 | ## Usage
 6 | 
 7 | ```ts
 8 | class MyElement extends LitElement {
 9 |   constructor() {
10 |     super();
11 | 
12 |     this._scrollCtrl = new WindowScrollController(this);
13 |   }
14 | 
15 |   render() {
16 |     return html`
17 |       X: ${this._scrollCtrl.x}
18 |       Y: ${this._scrollCtrl.y}
19 |     `;
20 |   }
21 | }
22 | ```
23 | 
24 | ## Options
25 | 
26 | N/A
27 | 


--------------------------------------------------------------------------------
/eslint.config.js:
--------------------------------------------------------------------------------
 1 | import eslintjs from '@eslint/js';
 2 | import {configs as tseslintConfigs} from 'typescript-eslint';
 3 | 
 4 | const {configs: eslintConfigs} = eslintjs;
 5 | 
 6 | export default [
 7 |   {
 8 |     ...eslintConfigs.recommended,
 9 |     files: ['src/**/*.ts'],
10 |   },
11 |   ...tseslintConfigs.strict,
12 |   {
13 |     rules: {
14 |       '@typescript-eslint/no-unused-vars': 'off'
15 |     }
16 |   },
17 |   {
18 |     files: ['src/test/**/*.ts'],
19 |     rules: {
20 |       '@typescript-eslint/no-non-null-assertion': 'off'
21 |     }
22 |   }
23 | ];
24 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "relit",
 3 |   "version": "0.0.0-dev",
 4 |   "description": "A collection of useful utilities for lit components",
 5 |   "main": "lib/main.js",
 6 |   "type": "module",
 7 |   "files": [
 8 |     "lib/",
 9 |     "!lib/test"
10 |   ],
11 |   "scripts": {
12 |     "clean": "rimraf ./lib",
13 |     "lint": "eslint \"src/**/*.ts\"",
14 |     "prebuild": "npm run clean",
15 |     "build": "tsc",
16 |     "test": "web-test-runner",
17 |     "format": "prettier --write \"src/**/*.ts\"",
18 |     "prepare": "npm run build",
19 |     "prepublishOnly": "npm run lint && npm run test"
20 |   },
21 |   "repository": {
22 |     "type": "git",
23 |     "url": "git+https://github.com/43081j/relit.git"
24 |   },
25 |   "author": "James Garbutt (https://github.com/43081j)",
26 |   "license": "MIT",
27 |   "bugs": {
28 |     "url": "https://github.com/43081j/relit/issues"
29 |   },
30 |   "homepage": "https://github.com/43081j/relit#readme",
31 |   "devDependencies": {
32 |     "@eslint/js": "^9.4.0",
33 |     "@types/mocha": "^10.0.1",
34 |     "@web/dev-server-esbuild": "^1.0.2",
35 |     "@web/test-runner": "^0.20.0",
36 |     "@web/test-runner-puppeteer": "^0.18.0",
37 |     "eslint": "^8.30.0",
38 |     "eslint-config-google": "^0.14.0",
39 |     "hanbi": "^1.0.1",
40 |     "lit": "^3.0.0",
41 |     "prettier": "^3.3.2",
42 |     "rimraf": "^5.0.7",
43 |     "typescript": "^5.4.5",
44 |     "typescript-eslint": "^7.13.0",
45 |     "uvu": "^0.5.6"
46 |   },
47 |   "peerDependencies": {
48 |     "lit": ">=2.5.0"
49 |   },
50 |   "dependencies": {
51 |     "@types/marked": "^4.0.8",
52 |     "marked": "^4.2.12",
53 |     "tslib": "^2.6.3"
54 |   }
55 | }
56 | 


--------------------------------------------------------------------------------
/src/_internal/elementTracking.ts:
--------------------------------------------------------------------------------
 1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
 2 | import type {Ref} from 'lit/directives/ref.js';
 3 | 
 4 | /**
 5 |  * Used to track an element's reference throughout the rendering
 6 |  * lifecycle.
 7 |  */
 8 | export class ElementTrackingController implements ReactiveController {
 9 |   protected _host: ReactiveControllerHost & Element;
10 |   protected _ref?: Ref;
11 |   private __currentElement: Element | undefined = undefined;
12 | 
13 |   /**
14 |    * Gets the current element being tracked
15 |    * @return {Element|undefined}
16 |    */
17 |   protected get _element(): Element | undefined {
18 |     if (this._ref) {
19 |       return this._ref.value;
20 |     }
21 |     return this._host;
22 |   }
23 | 
24 |   /**
25 |    * @param {Element} host Host element of this
26 |    * controller
27 |    * @param {Ref=} ref Ref to observe rather than the host element
28 |    */
29 |   public constructor(host: ReactiveControllerHost & Element, ref?: Ref | null) {
30 |     this._host = host;
31 |     if (ref) {
32 |       this._ref = ref;
33 |     }
34 |   }
35 | 
36 |   /** @inheritdoc */
37 |   public hostUpdated(): void {
38 |     const element = this._element;
39 |     const prevElement = this.__currentElement;
40 |     if (element !== prevElement) {
41 |       this.__currentElement = element;
42 |       this._onElementChanged(prevElement);
43 |     }
44 |   }
45 | 
46 |   /**
47 |    * Fired when the current observed element changed
48 |    * @param {Element|undefined} _previousElement Previous element before it
49 |    * changed
50 |    * @return {void}
51 |    */
52 |   protected _onElementChanged(_previousElement: Element | undefined): void {
53 |     return;
54 |   }
55 | }
56 | 


--------------------------------------------------------------------------------
/src/_internal/storage.ts:
--------------------------------------------------------------------------------
  1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
  2 | 
  3 | type CustomStorageEvent = CustomEvent<{storageArea: Storage; key: string}>;
  4 | type StorageEventLike = StorageEvent | CustomStorageEvent;
  5 | 
  6 | /**
  7 |  * Tracks the contents of a given storage mechanism
  8 |  */
  9 | export abstract class StorageController<T> implements ReactiveController {
 10 |   /**
 11 |    * Gets the current value
 12 |    * @return {T|undefined}
 13 |    */
 14 |   public get value(): T | undefined {
 15 |     return this.__value;
 16 |   }
 17 | 
 18 |   /**
 19 |    * Sets the current value
 20 |    * @param {T|undefined} newValue Value to set
 21 |    */
 22 |   public set value(newValue: T | undefined) {
 23 |     this.__writeValueToStorage(newValue);
 24 |   }
 25 | 
 26 |   private __value: T | undefined;
 27 |   private __storage: Storage;
 28 |   private __key: string;
 29 |   private __host: ReactiveControllerHost;
 30 |   private __initialValue: T | undefined;
 31 | 
 32 |   /**
 33 |    * @param {ReactiveControllerHost} host Host to attach to
 34 |    * @param {Storage} storage Storage to observe
 35 |    * @param {string} key Key to observe in the storage object
 36 |    * @param {T=} defaultValue Default value
 37 |    */
 38 |   public constructor(
 39 |     host: ReactiveControllerHost,
 40 |     storage: Storage,
 41 |     key: string,
 42 |     defaultValue?: T
 43 |   ) {
 44 |     this.__host = host;
 45 |     this.__storage = storage;
 46 |     this.__key = key;
 47 |     this.__initialValue = defaultValue;
 48 |     this.__value = this.__readValueFromStorage();
 49 | 
 50 |     host.addController(this);
 51 |   }
 52 | 
 53 |   /**
 54 |    * Fired when another window has changed a storage area
 55 |    * @param {StorageEvent} ev Event fired
 56 |    * @return {void}
 57 |    */
 58 |   private __onStorage = (ev: StorageEventLike): void => {
 59 |     const detail =
 60 |       ev.type === 'storage'
 61 |         ? (ev as StorageEvent)
 62 |         : (ev as CustomStorageEvent).detail;
 63 | 
 64 |     if (detail.storageArea === this.__storage && detail.key === this.__key) {
 65 |       const currentValue = this.__readValueFromStorage();
 66 |       this.__value = currentValue;
 67 |       this.__host.requestUpdate();
 68 |     }
 69 |   };
 70 | 
 71 |   /**
 72 |    * Updates the value in the given storage area
 73 |    * @param {T|undefined} val Value to write
 74 |    * @return {void}
 75 |    */
 76 |   private __writeValueToStorage(val: T | undefined): void {
 77 |     if (val === undefined) {
 78 |       this.__storage.removeItem(this.__key);
 79 |     } else {
 80 |       this.__storage.setItem(this.__key, JSON.stringify(val));
 81 |     }
 82 | 
 83 |     window.dispatchEvent(
 84 |       new CustomEvent<CustomStorageEvent['detail']>('__litkit-storage', {
 85 |         detail: {
 86 |           storageArea: this.__storage,
 87 |           key: this.__key
 88 |         }
 89 |       })
 90 |     );
 91 |   }
 92 | 
 93 |   /**
 94 |    * Updates the value from the given storage area
 95 |    * @return {void}
 96 |    */
 97 |   private __readValueFromStorage(): T | undefined {
 98 |     const json = this.__storage.getItem(this.__key);
 99 | 
100 |     if (json !== null) {
101 |       return JSON.parse(json) as T;
102 |     }
103 | 
104 |     return undefined;
105 |   }
106 | 
107 |   /** @inheritdoc */
108 |   public hostConnected(): void {
109 |     window.addEventListener('storage', this.__onStorage);
110 |     window.addEventListener('__litkit-storage', this.__onStorage);
111 | 
112 |     if (this.__initialValue !== undefined) {
113 |       const defaultValue = this.__initialValue;
114 |       const currentValue = this.__readValueFromStorage();
115 | 
116 |       if (currentValue === undefined && defaultValue !== undefined) {
117 |         this.__writeValueToStorage(defaultValue);
118 |       }
119 | 
120 |       this.__initialValue = undefined;
121 |     }
122 |   }
123 | 
124 |   /** @inheritdoc */
125 |   public hostDisconnected(): void {
126 |     window.removeEventListener('storage', this.__onStorage);
127 |     window.removeEventListener('__litkit-storage', this.__onStorage);
128 |   }
129 | }
130 | 
131 | declare global {
132 |   interface WindowEventMap {
133 |     '__litkit-storage': StorageEventLike;
134 |   }
135 | }
136 | 


--------------------------------------------------------------------------------
/src/controllers/activeElement.ts:
--------------------------------------------------------------------------------
 1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
 2 | 
 3 | /**
 4 |  * Tracks the active element of a document or document fragment
 5 |  */
 6 | export class ActiveElementController implements ReactiveController {
 7 |   public activeElement: DocumentOrShadowRoot['activeElement'];
 8 | 
 9 |   private __host: ReactiveControllerHost;
10 |   private __boundOnFocus: (ev: FocusEvent) => void;
11 |   private __document: DocumentOrShadowRoot;
12 | 
13 |   /**
14 |    * @param {ReactiveControllerHost} host Host to attach to
15 |    * @param {DocumentOrShadowRoot} doc Custom document to observe
16 |    */
17 |   public constructor(
18 |     host: ReactiveControllerHost,
19 |     doc: DocumentOrShadowRoot = window.document
20 |   ) {
21 |     this.__host = host;
22 |     this.__document = doc;
23 |     this.__boundOnFocus = this.__onFocus.bind(this);
24 | 
25 |     this.activeElement = doc.activeElement;
26 | 
27 |     host.addController(this);
28 |   }
29 | 
30 |   /**
31 |    * Fired when the focus has changed in the window
32 |    * @return {void}
33 |    */
34 |   private __onFocus(): void {
35 |     this.activeElement = this.__document.activeElement;
36 |     this.__host.requestUpdate();
37 |   }
38 | 
39 |   /** @inheritdoc */
40 |   public hostConnected(): void {
41 |     window.addEventListener('focusin', this.__boundOnFocus);
42 |     window.addEventListener('focusout', this.__boundOnFocus);
43 |   }
44 | 
45 |   /** @inheritdoc */
46 |   public hostDisconnected(): void {
47 |     window.removeEventListener('focusin', this.__boundOnFocus);
48 |     window.removeEventListener('focusout', this.__boundOnFocus);
49 |   }
50 | }
51 | 


--------------------------------------------------------------------------------
/src/controllers/documentVisibility.ts:
--------------------------------------------------------------------------------
 1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
 2 | 
 3 | /**
 4 |  * Tracks the document's current visibility
 5 |  */
 6 | export class DocumentVisibilityController implements ReactiveController {
 7 |   public visible: boolean = false;
 8 | 
 9 |   private __host: ReactiveControllerHost;
10 |   private __boundOnVisibilityChanged: () => void;
11 | 
12 |   /**
13 |    * @param {ReactiveControllerHost} host Host to attach to
14 |    */
15 |   public constructor(host: ReactiveControllerHost) {
16 |     this.__host = host;
17 |     this.__boundOnVisibilityChanged = this.__onVisibilityChanged.bind(this);
18 | 
19 |     this.visible = window.document.visibilityState === 'visible';
20 | 
21 |     host.addController(this as ReactiveController);
22 |   }
23 | 
24 |   /**
25 |    * Fired when the focus has changed in the window
26 |    * @return {void}
27 |    */
28 |   private __onVisibilityChanged(): void {
29 |     this.visible = window.document.visibilityState === 'visible';
30 |     this.__host.requestUpdate();
31 |   }
32 | 
33 |   /** @inheritdoc */
34 |   public hostConnected(): void {
35 |     window.addEventListener(
36 |       'visibilitychange',
37 |       this.__boundOnVisibilityChanged
38 |     );
39 |   }
40 | 
41 |   /** @inheritdoc */
42 |   public hostDisconnected(): void {
43 |     window.removeEventListener(
44 |       'visibilitychange',
45 |       this.__boundOnVisibilityChanged
46 |     );
47 |   }
48 | }
49 | 


--------------------------------------------------------------------------------
/src/controllers/elementSize.ts:
--------------------------------------------------------------------------------
 1 | import type {ReactiveControllerHost} from 'lit';
 2 | import type {Ref} from 'lit/directives/ref.js';
 3 | import {ElementTrackingController} from '../_internal/elementTracking.js';
 4 | 
 5 | export interface ElementSize {
 6 |   width: number;
 7 |   height: number;
 8 | }
 9 | 
10 | export type ElementSizeType = 'content' | 'border' | 'device';
11 | 
12 | export type ElementSizeProp =
13 |   | 'contentBoxSize'
14 |   | 'borderBoxSize'
15 |   | 'devicePixelContentBoxSize';
16 | 
17 | const elementSizeToProperty: Record<ElementSizeType, ElementSizeProp> = {
18 |   content: 'contentBoxSize',
19 |   border: 'borderBoxSize',
20 |   device: 'devicePixelContentBoxSize'
21 | };
22 | 
23 | const elementSizeToObserverOption: Record<
24 |   ElementSizeType,
25 |   ResizeObserverBoxOptions
26 | > = {
27 |   content: 'content-box',
28 |   border: 'border-box',
29 |   device: 'device-pixel-content-box'
30 | };
31 | 
32 | /**
33 |  * Tracks the size of a given element
34 |  */
35 | export class ElementSizeController extends ElementTrackingController {
36 |   public size: ElementSize;
37 | 
38 |   private __observer: ResizeObserver;
39 |   private __type: ElementSizeType;
40 | 
41 |   /**
42 |    * @param {ReactiveControllerHost} host Host to attach to
43 |    * @param {string} type Type of size to observe
44 |    * @param {Ref=} ref Ref to observe rather than the host element
45 |    */
46 |   public constructor(
47 |     host: ReactiveControllerHost & Element,
48 |     type: ElementSizeType = 'content',
49 |     ref?: Ref
50 |   ) {
51 |     super(host, ref);
52 |     this.__type = type;
53 |     this.size = {width: 0, height: 0};
54 | 
55 |     this.__observer = new ResizeObserver((entries) => this.__onResize(entries));
56 | 
57 |     host.addController(this);
58 |   }
59 | 
60 |   /**
61 |    * Fired when a resize occurs
62 |    * @param {ResizeObserverEntry[]} entries Resize entries
63 |    * @return {void}
64 |    */
65 |   private __onResize(entries: ResizeObserverEntry[]): void {
66 |     const element = this._element;
67 |     const entry = entries.find(({target}) => target === element);
68 | 
69 |     if (!entry) {
70 |       return;
71 |     }
72 | 
73 |     const dimension = entry[elementSizeToProperty[this.__type]];
74 | 
75 |     this.size = {
76 |       width: dimension.reduce((p, c) => p + c.inlineSize, 0),
77 |       height: dimension.reduce((p, c) => p + c.blockSize, 0)
78 |     };
79 | 
80 |     this._host.requestUpdate();
81 |   }
82 | 
83 |   /** @inheritdoc */
84 |   protected override _onElementChanged(prevElement: Element | undefined): void {
85 |     super._onElementChanged(prevElement);
86 | 
87 |     this.__observer.disconnect();
88 | 
89 |     const element = this._element;
90 | 
91 |     if (element) {
92 |       const box = elementSizeToObserverOption[this.__type];
93 |       this.__observer.observe(element, {box});
94 |     }
95 |   }
96 | }
97 | 


--------------------------------------------------------------------------------
/src/controllers/elementVisibility.ts:
--------------------------------------------------------------------------------
 1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
 2 | import type {Ref} from 'lit/directives/ref.js';
 3 | import {ElementTrackingController} from '../_internal/elementTracking.js';
 4 | 
 5 | /**
 6 |  * Tracks the visibility of an element
 7 |  */
 8 | export class ElementVisibilityController extends ElementTrackingController {
 9 |   public visible: boolean = true;
10 | 
11 |   private __observer: IntersectionObserver;
12 | 
13 |   /**
14 |    * @param {ReactiveControllerHost} host Host to attach to
15 |    * @param {Ref=} ref Ref to observe instead of the host element
16 |    */
17 |   public constructor(host: ReactiveControllerHost & Element, ref?: Ref) {
18 |     super(host, ref);
19 | 
20 |     this.__observer = new IntersectionObserver(
21 |       (entries) => this.__onIntersectionChange(entries),
22 |       {threshold: 1}
23 |     );
24 | 
25 |     const el = this._element;
26 | 
27 |     if (el) {
28 |       const rect = el.getBoundingClientRect();
29 |       this.visible = this.__computeVisibilityFromRect(rect);
30 |     }
31 | 
32 |     host.addController(this as ReactiveController);
33 |   }
34 | 
35 |   /**
36 |    * Fires when the intersection observer is triggered
37 |    * @param {IntersectionObserverEntry[]} entries Intersection changes
38 |    * @return {void}
39 |    */
40 |   private __onIntersectionChange(entries: IntersectionObserverEntry[]): void {
41 |     const el = this._element;
42 | 
43 |     if (!el) {
44 |       return;
45 |     }
46 | 
47 |     const entry = entries.find((e) => e.target === el);
48 | 
49 |     if (!entry) {
50 |       return;
51 |     }
52 | 
53 |     this.visible = entry.isIntersecting;
54 |     this._host.requestUpdate();
55 |   }
56 | 
57 |   /** @inheritdoc */
58 |   protected override _onElementChanged(): void {
59 |     this.__observer.disconnect();
60 | 
61 |     const el = this._element;
62 | 
63 |     if (el) {
64 |       this.__observer.observe(el);
65 |     }
66 |   }
67 | 
68 |   /**
69 |    * Computes the visibility from a DOM rect
70 |    * @param {DOMRect} rect Rect to calculate visibility from
71 |    * @return {boolean}
72 |    */
73 |   private __computeVisibilityFromRect(rect: DOMRect): boolean {
74 |     return (
75 |       rect.top <= window.innerHeight &&
76 |       rect.left <= window.innerWidth &&
77 |       rect.bottom >= 0 &&
78 |       rect.right >= 0
79 |     );
80 |   }
81 | }
82 | 


--------------------------------------------------------------------------------
/src/controllers/head.ts:
--------------------------------------------------------------------------------
  1 | import type {
  2 |   ReactiveController,
  3 |   ReactiveControllerHost,
  4 |   TemplateResult
  5 | } from 'lit';
  6 | import {render} from 'lit';
  7 | 
  8 | const supportedTags: Array<keyof HTMLElementTagNameMap> = [
  9 |   'title',
 10 |   'base',
 11 |   'meta',
 12 |   'link',
 13 |   'script',
 14 |   'noscript',
 15 |   'style'
 16 | ];
 17 | 
 18 | /**
 19 |  * Manages the `<head>` and other document-level states
 20 |  */
 21 | export class HeadController implements ReactiveController {
 22 |   public titleTemplate?: string;
 23 |   public defaultTitle?: string;
 24 | 
 25 |   private __host: ReactiveControllerHost;
 26 |   private __document: Document;
 27 |   private __updateContainer: DocumentFragment;
 28 |   private __trackedNodes: WeakSet<Node>;
 29 | 
 30 |   /**
 31 |    * @param {ReactiveControllerHost} host Host to attach to
 32 |    * @param {Document} doc Custom document to observe
 33 |    */
 34 |   public constructor(
 35 |     host: ReactiveControllerHost,
 36 |     doc: Document = window.document
 37 |   ) {
 38 |     this.__host = host;
 39 |     this.__document = doc;
 40 |     this.__updateContainer = doc.createDocumentFragment();
 41 |     this.__trackedNodes = new WeakSet<Node>();
 42 | 
 43 |     host.addController(this);
 44 |   }
 45 | 
 46 |   /** @inheritdoc */
 47 |   public hostConnected(): void {
 48 |     if (this.defaultTitle) {
 49 |       this.setTitle(this.defaultTitle);
 50 |     }
 51 |   }
 52 | 
 53 |   /**
 54 |    * Sets the page title
 55 |    * @param {string} title Title to set
 56 |    * @return {void}
 57 |    */
 58 |   public setTitle(title: string): void {
 59 |     const newTitle = this.titleTemplate
 60 |       ? this.titleTemplate.replace('%s', title)
 61 |       : title;
 62 |     this.__document.title = newTitle;
 63 |   }
 64 | 
 65 |   /**
 66 |    * Updates the document with the given template
 67 |    * @param {TemplateResult} template Template to apply
 68 |    * @return {void}
 69 |    */
 70 |   public update(template: TemplateResult): void {
 71 |     const doc = this.__document;
 72 | 
 73 |     render(template, this.__updateContainer, {host: this.__host});
 74 | 
 75 |     // TODO (43081j): maybe instead of nuking it every time we could
 76 |     // do some smart diff and only update whats needed?
 77 |     // who knows
 78 |     this.removeRenderedElements();
 79 | 
 80 |     for (const child of this.__updateContainer.children) {
 81 |       if (
 82 |         supportedTags.includes(
 83 |           child.nodeName.toLowerCase() as keyof HTMLElementTagNameMap
 84 |         )
 85 |       ) {
 86 |         this.__updateDocumentFromTemplate(doc, child);
 87 |       }
 88 |     }
 89 |   }
 90 | 
 91 |   /**
 92 |    * Removes all elements this controller has rendered
 93 |    * @return {void}
 94 |    */
 95 |   public removeRenderedElements(): void {
 96 |     const doc = this.__document;
 97 |     const children = [...doc.head.children];
 98 |     for (const child of children) {
 99 |       if (this.__trackedNodes.has(child)) {
100 |         child.remove();
101 |         this.__trackedNodes.delete(child);
102 | 
103 |         if (child.nodeName === 'TITLE' && this.defaultTitle) {
104 |           this.setTitle(this.defaultTitle);
105 |         }
106 |       }
107 |     }
108 |   }
109 | 
110 |   /**
111 |    * Updates the document body's attributes
112 |    * @param {Record<string, string>} attribs Attributes to apply
113 |    * @return {void}
114 |    */
115 |   public updateBodyAttr(attribs: Record<string, string | null>): void {
116 |     const node = this.__document.body;
117 |     this.__applyAttributesFromRecord(node, attribs);
118 |   }
119 | 
120 |   /**
121 |    * Updates the document's HTML tag's attributes
122 |    * @param {Record<string, string>} attribs Attributes to apply
123 |    * @return {void}
124 |    */
125 |   public updateHtmlAttr(attribs: Record<string, string | null>): void {
126 |     const node = this.__document.documentElement;
127 |     this.__applyAttributesFromRecord(node, attribs);
128 |   }
129 | 
130 |   /**
131 |    * Applies attributes from a record to a given node
132 |    * @param {Element} node Node to update
133 |    * @param {Record<string, string>} attribs Attributes to apply
134 |    * @return {void}
135 |    */
136 |   private __applyAttributesFromRecord(
137 |     node: Element,
138 |     attribs: Record<string, string | null>
139 |   ): void {
140 |     for (const [attr, value] of Object.entries(attribs)) {
141 |       if (value === null) {
142 |         node.removeAttribute(attr);
143 |       } else {
144 |         node.setAttribute(attr, value);
145 |       }
146 |     }
147 |   }
148 | 
149 |   /**
150 |    * Replaces a given node with a template, or creates it if it doesn't exist
151 |    * @param {Element} parentElement Parent element to append to if the node
152 |    * doesn't exist yet
153 |    * @param {HTMLTitleElement} template Title element to apply
154 |    * @param {Element} existingNode Node to replace, if any
155 |    * @return {void}
156 |    */
157 |   private __replaceOrCreateNodeFromTemplate(
158 |     parentElement: Element,
159 |     template: Element,
160 |     existingNode: Element | null
161 |   ): void {
162 |     const newNode = template.cloneNode(true);
163 |     this.__trackedNodes.add(newNode);
164 | 
165 |     if (existingNode) {
166 |       existingNode.replaceWith(newNode);
167 |     } else {
168 |       parentElement.appendChild(newNode);
169 |     }
170 |   }
171 | 
172 |   /**
173 |    * Updates the document's equivalent element for a given template
174 |    * @param {Document} doc Document to update
175 |    * @param {Element} template Template element to use as a source
176 |    * @return {void}
177 |    */
178 |   private __updateDocumentFromTemplate(doc: Document, template: Element): void {
179 |     switch (template.nodeName) {
180 |       case 'TITLE': {
181 |         this.__replaceOrCreateNodeFromTemplate(
182 |           doc.head,
183 |           template,
184 |           doc.head.querySelector('title')
185 |         );
186 |         break;
187 |       }
188 |       case 'BASE': {
189 |         this.__replaceOrCreateNodeFromTemplate(
190 |           doc.head,
191 |           template,
192 |           doc.head.querySelector('base')
193 |         );
194 |         break;
195 |       }
196 |       case 'LINK':
197 |       case 'SCRIPT':
198 |       case 'NOSCRIPT':
199 |       case 'STYLE':
200 |       case 'META': {
201 |         this.__replaceOrCreateNodeFromTemplate(doc.head, template, null);
202 |         break;
203 |       }
204 |     }
205 |   }
206 | }
207 | 


--------------------------------------------------------------------------------
/src/controllers/itemSelection.ts:
--------------------------------------------------------------------------------
  1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
  2 | 
  3 | export interface ItemSelectionOptions<T> {
  4 |   multiSelect?: boolean;
  5 |   defaultSelectedIndices?: number[];
  6 |   defaultSelection?: T[];
  7 | }
  8 | 
  9 | /**
 10 |  * Tracks the selected items in a set of items
 11 |  */
 12 | export class ItemSelectionController<T> {
 13 |   /**
 14 |    * Gets the selected items
 15 |    * @return {T[]}
 16 |    */
 17 |   public get selectedItems(): T[] {
 18 |     return this.items.filter((_item, idx) => this.__selectedIndices.has(idx));
 19 |   }
 20 | 
 21 |   /**
 22 |    * Gets the current set of items
 23 |    * @return {T[]}
 24 |    */
 25 |   public get items(): T[] {
 26 |     if (this.__itemsGetter) {
 27 |       return this.__itemsGetter();
 28 |     }
 29 |     return this.__items;
 30 |   }
 31 | 
 32 |   private __selectedIndices: Set<number> = new Set<number>();
 33 |   private __items: T[] = [];
 34 |   private __itemsGetter?: () => T[];
 35 |   private __host: ReactiveControllerHost;
 36 |   private __options?: ItemSelectionOptions<T>;
 37 | 
 38 |   /**
 39 |    * @param {ReactiveControllerHost} host Host to attach to
 40 |    * @param {T[]} items Set of items to select within
 41 |    * @param {object} options Options for item selection
 42 |    */
 43 |   public constructor(
 44 |     host: ReactiveControllerHost,
 45 |     items: T[] | (() => T[]),
 46 |     options?: ItemSelectionOptions<T>
 47 |   ) {
 48 |     this.__host = host;
 49 |     if (typeof items === 'function') {
 50 |       this.__itemsGetter = items;
 51 |     } else {
 52 |       this.__items = items;
 53 |     }
 54 | 
 55 |     if (options) {
 56 |       this.__options = options;
 57 | 
 58 |       if (options.defaultSelectedIndices) {
 59 |         for (const idx of options.defaultSelectedIndices) {
 60 |           this.selectByIndex(idx);
 61 |         }
 62 |       } else if (options.defaultSelection) {
 63 |         for (const item of options.defaultSelection) {
 64 |           this.select(item);
 65 |         }
 66 |       }
 67 |     }
 68 | 
 69 |     host.addController(this as ReactiveController);
 70 |   }
 71 | 
 72 |   /**
 73 |    * If in single-selection mode, selects the next item if one exists
 74 |    * @return {void}
 75 |    */
 76 |   public next(): void {
 77 |     if (this.__options?.multiSelect === true) {
 78 |       throw new Error('next() cannot be used when in multi-select mode');
 79 |     }
 80 | 
 81 |     this.selectByOffset(1);
 82 |   }
 83 | 
 84 |   /**
 85 |    * If in single-selection mode, selects the previous item if one exists
 86 |    * @return {void}
 87 |    */
 88 |   public prev(): void {
 89 |     if (this.__options?.multiSelect === true) {
 90 |       throw new Error('prev() cannot be used when in multi-select mode');
 91 |     }
 92 | 
 93 |     this.selectByOffset(-1);
 94 |   }
 95 | 
 96 |   /**
 97 |    * If in single-selection mode, selects an item in relation to the
 98 |    * current selection by an offset.
 99 |    * @param {number} offset Offset to select by
100 |    * @return {void}
101 |    */
102 |   public selectByOffset(offset: number): void {
103 |     if (this.__options?.multiSelect === true) {
104 |       throw new Error(
105 |         'selectByOffset() cannot be used when in multi-select mode'
106 |       );
107 |     }
108 | 
109 |     const [currentSelection] = [...this.__selectedIndices];
110 |     const items = this.items;
111 |     let newIndex = 0;
112 | 
113 |     if (currentSelection !== undefined) {
114 |       newIndex = currentSelection + offset;
115 | 
116 |       if (newIndex < 0) {
117 |         newIndex = 0;
118 |       } else if (newIndex >= items.length) {
119 |         newIndex = items.length - 1;
120 |       }
121 |     }
122 | 
123 |     this.deselectAll();
124 |     this.selectByIndex(newIndex);
125 |   }
126 | 
127 |   /**
128 |    * Selects the item at the given index
129 |    * @param {number} idx Index to select
130 |    * @return {void}
131 |    */
132 |   public selectByIndex(idx: number): void {
133 |     this.toggleByIndex(idx, true);
134 |   }
135 | 
136 |   /**
137 |    * Selects the given item
138 |    * @param {T} item Item to select
139 |    * @return {void}
140 |    */
141 |   public select(item: T): void {
142 |     this.toggle(item, true);
143 |   }
144 | 
145 |   /**
146 |    * Selects all items
147 |    * @return {void}
148 |    */
149 |   public selectAll(): void {
150 |     if (this.__options?.multiSelect !== true) {
151 |       throw new Error('selectAll() cannot be used when in single-select mode');
152 |     }
153 | 
154 |     const items = this.items;
155 | 
156 |     for (const item of items) {
157 |       this.select(item);
158 |     }
159 |   }
160 | 
161 |   /**
162 |    * Deselects all items
163 |    * @return {void}
164 |    */
165 |   public deselectAll(): void {
166 |     this.__selectedIndices.clear();
167 |     this.__host.requestUpdate();
168 |   }
169 | 
170 |   /**
171 |    * Deselects the given item
172 |    * @param {T} item Item to select
173 |    * @return {void}
174 |    */
175 |   public deselect(item: T): void {
176 |     this.toggle(item, false);
177 |   }
178 | 
179 |   /**
180 |    * Deselects the item at the given index
181 |    * @param {number} idx Index to deselect
182 |    * @return {void}
183 |    */
184 |   public deselectByIndex(idx: number): void {
185 |     this.toggleByIndex(idx, false);
186 |   }
187 | 
188 |   /**
189 |    * Toggles the selection of the item at the given index
190 |    * @param {number} idx Index of item to toggle
191 |    * @param {boolean=} selected Force selection state rather than inverting it
192 |    * @return {void}
193 |    */
194 |   public toggleByIndex(idx: number, selected?: boolean): void {
195 |     if (idx < 0) {
196 |       throw new Error('Index cannot be below 0');
197 |     }
198 | 
199 |     const items = this.items;
200 | 
201 |     if (idx >= items.length) {
202 |       throw new Error('Index cannot be greater than size of items array');
203 |     }
204 | 
205 |     const multiSelect = this.__options?.multiSelect === true;
206 |     const isSelected = this.__selectedIndices.has(idx);
207 |     const newState = selected ?? !isSelected;
208 | 
209 |     if (newState && !multiSelect) {
210 |       this.__selectedIndices.clear();
211 |     }
212 | 
213 |     if (newState) {
214 |       this.__selectedIndices.add(idx);
215 |     } else {
216 |       this.__selectedIndices.delete(idx);
217 |     }
218 | 
219 |     this.__host.requestUpdate();
220 |   }
221 | 
222 |   /**
223 |    * Toggles the selection of the given item
224 |    * @param {T} item Item to toggle
225 |    * @param {boolean=} selected Force selection state rather than inverting it
226 |    * @return {void}
227 |    */
228 |   public toggle(item: T, selected?: boolean): void {
229 |     const idx = this.items.indexOf(item);
230 | 
231 |     if (idx === -1) {
232 |       throw new Error('Item was not in items array');
233 |     }
234 | 
235 |     this.toggleByIndex(idx, selected);
236 |   }
237 | }
238 | 


--------------------------------------------------------------------------------
/src/controllers/keyBinding.ts:
--------------------------------------------------------------------------------
  1 | import type {ReactiveControllerHost} from 'lit';
  2 | import type {Ref} from 'lit/directives/ref.js';
  3 | import {ElementTrackingController} from '../_internal/elementTracking.js';
  4 | 
  5 | export type KeyBindingHandler = (ev: KeyboardEvent) => void;
  6 | export type KeyBindingTrigger = 'keydown' | 'keyup' | 'firstKeyDown';
  7 | export interface KeyBindingOptions {
  8 |   triggers?: KeyBindingTrigger[];
  9 | }
 10 | 
 11 | interface KeyBinding {
 12 |   keys: string[];
 13 |   handler: KeyBindingHandler;
 14 |   options?: KeyBindingOptions | undefined;
 15 | }
 16 | 
 17 | export interface KeyBindingGlobalOptions {
 18 |   ignoredElements?: string[];
 19 | }
 20 | 
 21 | const defaultOptions: KeyBindingGlobalOptions = {
 22 |   ignoredElements: ['textarea', 'input', 'select']
 23 | };
 24 | 
 25 | /**
 26 |  * Normalises the keys input to an array
 27 |  * @param {string|string[]} keys Keys to normalise
 28 |  * @return {string[]}
 29 |  */
 30 | function normaliseKeys(keys: string | string[]): string[] {
 31 |   return (Array.isArray(keys) ? keys : [keys]).map((k) => k.toLowerCase());
 32 | }
 33 | 
 34 | /**
 35 |  * Determines if an event target is an element
 36 |  * @param {EventTarget} node Node to test
 37 |  * @return {boolean}
 38 |  */
 39 | function isElement(node: EventTarget): node is Element {
 40 |   return (node as Element).nodeType === Node.ELEMENT_NODE;
 41 | }
 42 | 
 43 | /**
 44 |  * Enables key bindings in a host element
 45 |  */
 46 | export class KeyBindingController extends ElementTrackingController {
 47 |   private __bindings: Set<KeyBinding> = new Set<KeyBinding>();
 48 |   private __options: KeyBindingGlobalOptions;
 49 |   private __pressedKeys: Set<string> = new Set<string>();
 50 |   private __firstKeyDownHistory: WeakSet<KeyBinding> =
 51 |     new WeakSet<KeyBinding>();
 52 | 
 53 |   /**
 54 |    * @param {ReactiveControllerHost} host Host to attach to
 55 |    * @param {Ref=} ref Ref to observe rather than the host element
 56 |    * @param {KeyBindingGlobalOptions=} options Options for the controller
 57 |    */
 58 |   public constructor(
 59 |     host: ReactiveControllerHost & Element,
 60 |     ref?: Ref | null,
 61 |     options?: KeyBindingGlobalOptions
 62 |   ) {
 63 |     super(host, ref);
 64 | 
 65 |     this.__options = {
 66 |       ...defaultOptions,
 67 |       ...options
 68 |     };
 69 | 
 70 |     host.addController(this);
 71 |   }
 72 | 
 73 |   /**
 74 |    * Binds a key combination to a specified function
 75 |    * @param {string|string[]} key Key to bind, or key-combination if
 76 |    * it is an array.
 77 |    * @param {KeyBindingHandler} fn Callback function
 78 |    * @param {KeyBindingOptions=} options Options for binding
 79 |    * @return {void}
 80 |    */
 81 |   public bindKey(
 82 |     key: string | string[],
 83 |     fn: KeyBindingHandler,
 84 |     options?: KeyBindingOptions
 85 |   ): void {
 86 |     this.__bindings.add({
 87 |       keys: normaliseKeys(key),
 88 |       handler: fn,
 89 |       options
 90 |     });
 91 |   }
 92 | 
 93 |   /**
 94 |    * Binds a key combination to the focusing of a specified element
 95 |    * @param {string|string[]} key Key to bind, or key-combination if
 96 |    * it is an array.
 97 |    * @param {Ref} ref Element ref to focus on key press
 98 |    * @return {void}
 99 |    */
100 |   public bindFocus(key: string | string[], ref: Ref): void {
101 |     this.__bindings.add({
102 |       keys: normaliseKeys(key),
103 |       handler: () => this.__focusRef(ref)
104 |     });
105 |   }
106 | 
107 |   /**
108 |    * Focuses a ref based on an event
109 |    * @param {Ref} ref Ref to element to focus
110 |    * @return {void}
111 |    */
112 |   private __focusRef(ref: Ref): void {
113 |     if (ref.value) {
114 |       const withFocus = ref.value as Element & {focus?: () => void};
115 | 
116 |       if (withFocus.focus) {
117 |         withFocus.focus();
118 |       }
119 |     }
120 |   }
121 | 
122 |   /**
123 |    * Binds a key combination to behave like a "push and release" toggle.
124 |    * For example, assuming we bound the `c` key, it means our
125 |    * function would be called when we initially push it and when we
126 |    * finally release it.
127 |    * @param {string|string[]} key Key to bind, or key-combination if
128 |    * it is an array.
129 |    * @param {KeyBindingHandler} fn Callback function
130 |    * @return {void}
131 |    */
132 |   public bindPush(key: string | string[], fn: KeyBindingHandler): void {
133 |     this.__bindings.add({
134 |       keys: normaliseKeys(key),
135 |       handler: fn,
136 |       options: {
137 |         triggers: ['firstKeyDown', 'keyup']
138 |       }
139 |     });
140 |   }
141 | 
142 |   /**
143 |    * Handles a keyboard event by executing any matching bindings
144 |    * @param {KeyboardEvent} ev Event fired
145 |    * @return {void}
146 |    */
147 |   private __handleEvent(ev: KeyboardEvent): void {
148 |     const key = ev.key.toLowerCase();
149 |     const path = ev.composedPath();
150 |     const ignoredElements = this.__options?.ignoredElements;
151 | 
152 |     if (!this._element || !path.includes(this._element)) {
153 |       return;
154 |     }
155 | 
156 |     if (ignoredElements) {
157 |       const isIgnored = path.some(
158 |         (target) =>
159 |           isElement(target) &&
160 |           ignoredElements.some((selector) => target.matches(selector))
161 |       );
162 | 
163 |       if (isIgnored) {
164 |         return;
165 |       }
166 |     }
167 | 
168 |     if (ev.type === 'keydown') {
169 |       this.__pressedKeys.add(key);
170 |     }
171 | 
172 |     for (const binding of this.__bindings) {
173 |       if (this.__bindingMatches(binding, ev)) {
174 |         binding.handler.call(this._host, ev);
175 |       }
176 |     }
177 | 
178 |     if (ev.type === 'keyup') {
179 |       this.__pressedKeys.delete(key);
180 |     }
181 |   }
182 | 
183 |   /**
184 |    * Determines if a given key event matches a binding
185 |    * @param {KeyBinding} binding Binding to test
186 |    * @param {KeyboardEvent} ev Event fired
187 |    * @return {boolean}
188 |    */
189 |   private __bindingMatches(binding: KeyBinding, ev: KeyboardEvent): boolean {
190 |     const triggers = binding.options?.triggers ?? ['keyup'];
191 |     const keysMatch = binding.keys.every((key) => this.__pressedKeys.has(key));
192 | 
193 |     if (!keysMatch) {
194 |       return false;
195 |     }
196 | 
197 |     if (ev.type === 'keydown') {
198 |       if (triggers.includes('keydown')) {
199 |         return true;
200 |       }
201 | 
202 |       if (triggers.includes('firstKeyDown')) {
203 |         if (this.__firstKeyDownHistory.has(binding)) {
204 |           return false;
205 |         }
206 | 
207 |         this.__firstKeyDownHistory.add(binding);
208 |         return true;
209 |       }
210 |     }
211 | 
212 |     if (ev.type === 'keyup') {
213 |       this.__firstKeyDownHistory.delete(binding);
214 | 
215 |       if (triggers.includes('keyup')) {
216 |         return true;
217 |       }
218 |     }
219 | 
220 |     return false;
221 |   }
222 | 
223 |   /**
224 |    * Fired on keyup of the host
225 |    * @param {KeyboardEvent} ev Event fired
226 |    * @return {void}
227 |    */
228 |   private __onKeyUp = (ev: Event): void => {
229 |     const keyEvent = ev as KeyboardEvent;
230 |     this.__handleEvent(keyEvent);
231 |   };
232 | 
233 |   /**
234 |    * Fired on keydown of the host
235 |    * @param {KeyboardEvent} ev Event fired
236 |    * @return {void}
237 |    */
238 |   private __onKeyDown = (ev: Event): void => {
239 |     const keyEvent = ev as KeyboardEvent;
240 |     this.__handleEvent(keyEvent);
241 |   };
242 | 
243 |   /** @inheritdoc */
244 |   public hostConnected(): void {
245 |     this._host.addEventListener('keyup', this.__onKeyUp);
246 |     this._host.addEventListener('keydown', this.__onKeyDown);
247 |   }
248 | 
249 |   /** @inheritdoc */
250 |   public hostDisconnected(): void {
251 |     this._host.removeEventListener('keyup', this.__onKeyUp);
252 |     this._host.removeEventListener('keydown', this.__onKeyDown);
253 |   }
254 | }
255 | 


--------------------------------------------------------------------------------
/src/controllers/localStorage.ts:
--------------------------------------------------------------------------------
 1 | import {StorageController} from '../_internal/storage.js';
 2 | import {ReactiveControllerHost} from 'lit';
 3 | 
 4 | /**
 5 |  * Tracks the contents of a given key in local storage
 6 |  */
 7 | export class LocalStorageController<T> extends StorageController<T> {
 8 |   /**
 9 |    * @param {ReactiveControllerHost} host Host to attach to
10 |    * @param {string} key Key to observe in the storage object
11 |    * @param {T=} defaultValue Default value
12 |    */
13 |   public constructor(
14 |     host: ReactiveControllerHost,
15 |     key: string,
16 |     defaultValue?: T
17 |   ) {
18 |     super(host, window.localStorage, key, defaultValue);
19 |   }
20 | }
21 | 


--------------------------------------------------------------------------------
/src/controllers/markdown.ts:
--------------------------------------------------------------------------------
  1 | import {marked} from 'marked';
  2 | import type {
  3 |   ReactiveController,
  4 |   ReactiveControllerHost,
  5 |   TemplateResult
  6 | } from 'lit';
  7 | import {html} from 'lit';
  8 | import {unsafeHTML} from 'lit/directives/unsafe-html.js';
  9 | 
 10 | export interface MarkdownOptions<TKey> {
 11 |   markedOptions?: marked.MarkedOptions;
 12 |   property?: TKey;
 13 | }
 14 | 
 15 | /**
 16 |  * Processes markdown into a HTML result
 17 |  */
 18 | export class MarkdownController<
 19 |   T extends ReactiveControllerHost,
 20 |   TKey extends keyof T
 21 | > implements ReactiveController
 22 | {
 23 |   public value?: TemplateResult;
 24 | 
 25 |   /**
 26 |    * Gets the controller options
 27 |    * @return {MarkdownOptions<TKey>|undefined}
 28 |    */
 29 |   public get options(): MarkdownOptions<TKey> | undefined {
 30 |     return this.__options;
 31 |   }
 32 | 
 33 |   /**
 34 |    * Sets the controller options
 35 |    * @param {MarkdownOptions<TKey>} opts Options to set
 36 |    */
 37 |   public set options(opts: MarkdownOptions<TKey> | undefined) {
 38 |     const oldOpts = this.__options;
 39 | 
 40 |     this.__options = opts;
 41 | 
 42 |     if (oldOpts !== opts && this.__previousValue !== undefined) {
 43 |       this.__processMarkdownFromValue(this.__previousValue);
 44 |     }
 45 |   }
 46 | 
 47 |   private __host: T;
 48 |   private __options: MarkdownOptions<TKey> | undefined = undefined;
 49 |   private __previousValue?: string;
 50 | 
 51 |   /**
 52 |    * @param {ReactiveControllerHost} host Host to attach to
 53 |    * @param {MarkdownOptions=} options Options for the controller
 54 |    */
 55 |   public constructor(host: T, options?: MarkdownOptions<TKey>) {
 56 |     this.__host = host;
 57 |     this.__options = options;
 58 | 
 59 |     if (options?.property) {
 60 |       this.__setValueFromProp(options.property);
 61 |     }
 62 | 
 63 |     host.addController(this);
 64 |   }
 65 | 
 66 |   /**
 67 |    * Sets the value based on a host property
 68 |    * @param {string} prop Property containing markdown
 69 |    * @return {Promise<void>}
 70 |    */
 71 |   private async __setValueFromProp(prop: TKey): Promise<void> {
 72 |     const value = String(this.__host[prop]);
 73 | 
 74 |     if (value !== this.__previousValue) {
 75 |       await this.setValue(value);
 76 |     }
 77 |   }
 78 | 
 79 |   /** @inheritdoc */
 80 |   public hostUpdate(): void {
 81 |     if (this.__options?.property === undefined) {
 82 |       return;
 83 |     }
 84 | 
 85 |     this.__setValueFromProp(this.__options.property);
 86 |   }
 87 | 
 88 |   /**
 89 |    * Sets the markdown value and begins converting it to HTML
 90 |    * @param {string} markdown Markdown to parse
 91 |    * @return {Promise<void>}
 92 |    */
 93 |   public async setValue(markdown: string): Promise<void> {
 94 |     if (markdown === this.__previousValue) {
 95 |       return;
 96 |     }
 97 | 
 98 |     this.__previousValue = markdown;
 99 | 
100 |     this.__processMarkdownFromValue(markdown);
101 |   }
102 | 
103 |   /**
104 |    * Processes a given markdown string and sets the value of the controller
105 |    * @param {string} markdown Source to process
106 |    * @return {void}
107 |    */
108 |   private __processMarkdownFromValue(markdown: string): void {
109 |     const parsed = marked(markdown, {
110 |       ...this.__options?.markedOptions
111 |     });
112 | 
113 |     this.value = html`${unsafeHTML(parsed)}`;
114 |     this.__host.requestUpdate();
115 |   }
116 | }
117 | 


--------------------------------------------------------------------------------
/src/controllers/permissions.ts:
--------------------------------------------------------------------------------
 1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
 2 | 
 3 | /**
 4 |  * The permission state can be either 'denied', 'granted' or 'prompt'.
 5 |  * While querying the browser for the underlying state, the async permission
 6 |  * state will be set to `pending`.
 7 |  */
 8 | export type AsyncPermissionState = 'pending' | PermissionState;
 9 | 
10 | /**
11 |  * Tracks the status of a given browser permission
12 |  */
13 | export class PermissionsController {
14 |   /**
15 |    * Gets the current async permission state
16 |    * @return {AsyncPermissionState}
17 |    */
18 |   public get state(): AsyncPermissionState {
19 |     return this.__status?.state ?? 'pending';
20 |   }
21 | 
22 |   private __host: ReactiveControllerHost;
23 |   private __status?: PermissionStatus;
24 | 
25 |   /**
26 |    * @param {ReactiveControllerHost} host Host to attach to
27 |    * @param {PermissionName} name Permission to track
28 |    */
29 |   public constructor(host: ReactiveControllerHost, name: PermissionName) {
30 |     this.__host = host;
31 | 
32 |     this.__initialisePermissions(name);
33 | 
34 |     host.addController(this as ReactiveController);
35 |   }
36 | 
37 |   /**
38 |    * Initialises the permissions state and event handling
39 |    * @param {string} name Permission name
40 |    * @return {Promise<void>}
41 |    */
42 |   protected async __initialisePermissions(name: PermissionName): Promise<void> {
43 |     this.__status = await navigator.permissions.query({name});
44 |     this.__status.addEventListener('change', this.__onPermissionChanged);
45 |     // Request an update to reflect the initial state
46 |     this.__host.requestUpdate();
47 |   }
48 | 
49 |   protected __onPermissionChanged: () => void = (): void => {
50 |     this.__host.requestUpdate();
51 |   };
52 | }
53 | 


--------------------------------------------------------------------------------
/src/controllers/propertyHistory.ts:
--------------------------------------------------------------------------------
  1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
  2 | 
  3 | export interface PropertyHistoryEntry<T> {
  4 |   value: T;
  5 |   date: Date;
  6 | }
  7 | 
  8 | /**
  9 |  * Tracks the history of a given property
 10 |  */
 11 | export class PropertyHistoryController<
 12 |   T extends ReactiveControllerHost,
 13 |   TKey extends keyof T
 14 | > implements ReactiveController
 15 | {
 16 |   /**
 17 |    * Gets the date of the last change
 18 |    * @return {Date|undefined}
 19 |    */
 20 |   public get lastChanged(): Date | undefined {
 21 |     return this.__history[this.__currentIndex]?.date;
 22 |   }
 23 | 
 24 |   /**
 25 |    * Gets the current history index
 26 |    * @return {number}
 27 |    */
 28 |   private get __currentIndex(): number {
 29 |     const maxIndex = this.__history.length - 1;
 30 |     return this.__historyIndex === -1 ? maxIndex : this.__historyIndex;
 31 |   }
 32 | 
 33 |   private __host: T;
 34 |   private __propertyName: TKey;
 35 |   private __history: Array<PropertyHistoryEntry<T[TKey]>>;
 36 |   private __historyLimit: number = 4;
 37 |   private __historyIndex: number = -1;
 38 | 
 39 |   /**
 40 |    * @param {ReactiveControllerHost} host Host to attach to
 41 |    * @param {string} property Property name to observe
 42 |    */
 43 |   public constructor(host: T, property: TKey) {
 44 |     const value = host[property];
 45 | 
 46 |     this.__host = host;
 47 |     this.__propertyName = property;
 48 |     this.__history = [
 49 |       {
 50 |         value,
 51 |         date: new Date()
 52 |       }
 53 |     ];
 54 | 
 55 |     host.addController(this);
 56 |   }
 57 | 
 58 |   /** @inheritdoc */
 59 |   public hostUpdate(): void {
 60 |     const newValue = this.__host[this.__propertyName];
 61 |     const maxIndex = this.__history.length - 1;
 62 |     const currentIndex = this.__currentIndex;
 63 |     const currentValue = this.__history[currentIndex];
 64 | 
 65 |     if (newValue !== currentValue?.value) {
 66 |       this.__history.splice(currentIndex + 1, maxIndex - currentIndex, {
 67 |         value: newValue,
 68 |         date: new Date()
 69 |       });
 70 |       this.__historyIndex = -1;
 71 | 
 72 |       if (this.__history.length > this.__historyLimit) {
 73 |         this.__history.shift();
 74 |       }
 75 | 
 76 |       this.__host.requestUpdate();
 77 |     }
 78 |   }
 79 | 
 80 |   /**
 81 |    * Roll the current value back to the previous value
 82 |    * @return {void}
 83 |    */
 84 |   public undo(): void {
 85 |     this.__restoreValueByOffset(-1);
 86 |   }
 87 | 
 88 |   /**
 89 |    * Roll the current value forward to what it previously was
 90 |    * @return {void}
 91 |    */
 92 |   public redo(): void {
 93 |     this.__restoreValueByOffset(1);
 94 |   }
 95 | 
 96 |   /**
 97 |    * Restores the value by an offset in the history
 98 |    * @param {number} offset Offset to restore
 99 |    * @return {void}
100 |    */
101 |   private __restoreValueByOffset(offset: number): void {
102 |     const maxIndex = this.__history.length - 1;
103 |     const currentIndex = this.__currentIndex;
104 |     const newIndex = currentIndex + offset;
105 |     const prevValue = this.__history[newIndex];
106 | 
107 |     if (
108 |       currentIndex < 0 ||
109 |       newIndex < 0 ||
110 |       newIndex > maxIndex ||
111 |       prevValue === undefined
112 |     ) {
113 |       return;
114 |     }
115 | 
116 |     this.__host[this.__propertyName] = prevValue.value;
117 |     this.__historyIndex = newIndex === maxIndex ? -1 : newIndex;
118 |     prevValue.date = new Date();
119 |     this.__host.requestUpdate();
120 |   }
121 | }
122 | 


--------------------------------------------------------------------------------
/src/controllers/sessionStorage.ts:
--------------------------------------------------------------------------------
 1 | import {StorageController} from '../_internal/storage.js';
 2 | import {ReactiveControllerHost} from 'lit';
 3 | 
 4 | /**
 5 |  * Tracks the contents of a given key in session storage
 6 |  */
 7 | export class SessionStorageController<T> extends StorageController<T> {
 8 |   /**
 9 |    * @param {ReactiveControllerHost} host Host to attach to
10 |    * @param {string} key Key to observe in the storage object
11 |    * @param {T=} defaultValue Default value
12 |    */
13 |   public constructor(
14 |     host: ReactiveControllerHost,
15 |     key: string,
16 |     defaultValue?: T
17 |   ) {
18 |     super(host, window.sessionStorage, key, defaultValue);
19 |   }
20 | }
21 | 


--------------------------------------------------------------------------------
/src/controllers/slot.ts:
--------------------------------------------------------------------------------
  1 | import type {ReactiveControllerHost, ReactiveController} from 'lit';
  2 | import type {Ref} from 'lit/directives/ref.js';
  3 | 
  4 | /**
  5 |  * Determines if a node is a slot element
  6 |  * @param {Element} node Node to test
  7 |  * @return {boolean}
  8 |  */
  9 | function isSlotElement(node: Element): node is HTMLSlotElement {
 10 |   return node.nodeName === 'SLOT';
 11 | }
 12 | 
 13 | const defaultSlotName = '[default]';
 14 | 
 15 | /**
 16 |  * Determines if a given slot string/ref matches the specified slot
 17 |  * @param {HTMLSlotElement} node Node to test against
 18 |  * @param {string|Ref} matcher Ref or selector to match
 19 |  * @return {boolean}
 20 |  */
 21 | function slotMatches(
 22 |   node: HTMLSlotElement,
 23 |   matcher: string | Ref<HTMLSlotElement>
 24 | ): boolean {
 25 |   if (matcher === defaultSlotName && !node.hasAttribute('name')) {
 26 |     return true;
 27 |   }
 28 | 
 29 |   if (typeof matcher !== 'string') {
 30 |     return matcher.value === node;
 31 |   }
 32 | 
 33 |   return matcher === node.name;
 34 | }
 35 | 
 36 | /**
 37 |  * Determines the slot name from a string or ref
 38 |  * @param {string|Ref} slot Slot to retrieve name from
 39 |  * @return {string|null}
 40 |  */
 41 | function getSlotName(slot: string | Ref<HTMLSlotElement>): string | null {
 42 |   if (typeof slot === 'string') {
 43 |     return slot;
 44 |   }
 45 |   if (!slot.value) {
 46 |     return null;
 47 |   }
 48 |   return slot.value.name || '[default]';
 49 | }
 50 | 
 51 | type SlotListenerCallback<T extends Element> = (node: T) => void;
 52 | 
 53 | export interface HasOptions {
 54 |   flatten?: boolean;
 55 | }
 56 | 
 57 | interface SlotListener {
 58 |   slot: string | Ref<HTMLSlotElement>;
 59 |   selector: string;
 60 |   callback: SlotListenerCallback<Element>;
 61 | }
 62 | 
 63 | /**
 64 |  * Helpers for dealing with slotted content
 65 |  */
 66 | export class SlotController implements ReactiveController {
 67 |   private __host: ReactiveControllerHost & Element;
 68 |   private __hasCalled: boolean = false;
 69 |   private __listeners: Set<SlotListener> = new Set<SlotListener>();
 70 | 
 71 |   /**
 72 |    * Gets the slot elements in the current host
 73 |    * @return {HTMLSlotElement[]}
 74 |    */
 75 |   private get __slots(): HTMLSlotElement[] {
 76 |     if (!this.__host.shadowRoot) {
 77 |       return [];
 78 |     }
 79 | 
 80 |     return [...this.__host.shadowRoot.querySelectorAll('slot')];
 81 |   }
 82 | 
 83 |   /**
 84 |    * @param {ReactiveControllerHost} host Host to attach to
 85 |    */
 86 |   public constructor(host: ReactiveControllerHost & Element) {
 87 |     this.__host = host;
 88 | 
 89 |     host.addController(this);
 90 |   }
 91 | 
 92 |   /**
 93 |    * Determines if a given slot has contents in the host
 94 |    * @param {string|Ref} slot Slot to test against, * for all slots
 95 |    * @param {string} selector Selector to test
 96 |    * @param {object} options Options for detection
 97 |    * @return {boolean}
 98 |    */
 99 |   public has(
100 |     slot: string | Ref<HTMLSlotElement>,
101 |     selector?: string,
102 |     options?: HasOptions
103 |   ): boolean {
104 |     const slotName = getSlotName(slot);
105 |     const flatten = options?.flatten === true;
106 | 
107 |     this.__hasCalled = true;
108 | 
109 |     if (!slotName) {
110 |       return false;
111 |     }
112 | 
113 |     const slots = this.__slots.filter((slot) => {
114 |       return (
115 |         slotName === '*' ||
116 |         (!slot.hasAttribute('name') && slotName === defaultSlotName) ||
117 |         slot.name === slotName
118 |       );
119 |     });
120 | 
121 |     for (const slot of slots) {
122 |       for (const child of slot.assignedElements({flatten})) {
123 |         // If there's no selector, return as soon as we've seen a child.
124 |         // Otherwise, return once we see a matching child.
125 |         if (!selector || child.matches(selector)) {
126 |           return true;
127 |         }
128 |       }
129 |     }
130 | 
131 |     return false;
132 |   }
133 | 
134 |   /**
135 |    * Binds a function to be called any time elements matching the specified
136 |    * selector are slotted into a given slot
137 |    * @param {string|Ref} slot Slot to observe, * for all slots
138 |    * @param {string} selector Query selector to filter elements by. Set this
139 |    * to `*` for all elements
140 |    * @param {SlotListenerCallback} callback Callback to call
141 |    * @return {void}
142 |    */
143 |   public addListener<T extends keyof HTMLElementTagNameMap>(
144 |     slot: string | Ref<HTMLSlotElement>,
145 |     selector: T,
146 |     callback: SlotListenerCallback<HTMLElementTagNameMap[T]>
147 |   ): void;
148 | 
149 |   /** @inheritdoc */
150 |   public addListener(
151 |     slot: string | Ref<HTMLSlotElement>,
152 |     selector: string,
153 |     callback: SlotListenerCallback<Element>
154 |   ): void;
155 | 
156 |   /** @inheritdoc */
157 |   public addListener(
158 |     slot: string | Ref<HTMLSlotElement>,
159 |     selector: string,
160 |     callback: SlotListenerCallback<Element>
161 |   ): void {
162 |     this.__listeners.add({
163 |       slot,
164 |       selector,
165 |       callback
166 |     });
167 |   }
168 | 
169 |   /**
170 |    * Fired when a slot change event occurred
171 |    * @param {Event} ev Event fired
172 |    * @return {void}
173 |    */
174 |   private __onSlotChanged = (ev: Event): void => {
175 |     const element = ev.target as Element;
176 | 
177 |     if (!isSlotElement(element)) {
178 |       return;
179 |     }
180 | 
181 |     const nodes = element.assignedElements();
182 | 
183 |     for (const listener of this.__listeners) {
184 |       if (listener.slot !== '*' && !slotMatches(element, listener.slot)) {
185 |         continue;
186 |       }
187 | 
188 |       for (const node of nodes) {
189 |         if (listener.selector === '*' || node.matches(listener.selector)) {
190 |           listener.callback(node);
191 |         }
192 |       }
193 |     }
194 | 
195 |     if (this.__hasCalled) {
196 |       this.__host.requestUpdate();
197 |     }
198 |   };
199 | 
200 |   /** @inheritdoc */
201 |   public hostUpdate(): void {
202 |     this.__hasCalled = false;
203 |   }
204 | 
205 |   /** @inheritdoc */
206 |   public hostConnected(): void {
207 |     this.__host.shadowRoot?.addEventListener(
208 |       'slotchange',
209 |       this.__onSlotChanged
210 |     );
211 |   }
212 | 
213 |   /** @inheritdoc */
214 |   public hostDisconnected(): void {
215 |     this.__host.shadowRoot?.removeEventListener(
216 |       'slotchange',
217 |       this.__onSlotChanged
218 |     );
219 |   }
220 | }
221 | 


--------------------------------------------------------------------------------
/src/controllers/windowScroll.ts:
--------------------------------------------------------------------------------
 1 | import type {ReactiveController, ReactiveControllerHost} from 'lit';
 2 | 
 3 | /**
 4 |  * Tracks the scroll offset of the window
 5 |  */
 6 | export class WindowScrollController implements ReactiveController {
 7 |   public x: number = 0;
 8 |   public y: number = 0;
 9 | 
10 |   private __host: ReactiveControllerHost;
11 | 
12 |   /**
13 |    * @param {ReactiveControllerHost} host Host to attach to
14 |    */
15 |   public constructor(host: ReactiveControllerHost) {
16 |     this.__host = host;
17 | 
18 |     this.x = window.pageXOffset;
19 |     this.y = window.pageYOffset;
20 | 
21 |     host.addController(this);
22 |   }
23 | 
24 |   /**
25 |    * Fired when the window has been scrolled
26 |    * @return {void}
27 |    */
28 |   private __onScroll: () => void = (): void => {
29 |     this.x = window.pageXOffset;
30 |     this.y = window.pageYOffset;
31 |     this.__host.requestUpdate();
32 |   };
33 | 
34 |   /** @inheritdoc */
35 |   public hostConnected(): void {
36 |     window.addEventListener('scroll', this.__onScroll, {passive: true});
37 |   }
38 | 
39 |   /** @inheritdoc */
40 |   public hostDisconnected(): void {
41 |     window.removeEventListener('scroll', this.__onScroll);
42 |   }
43 | }
44 | 


--------------------------------------------------------------------------------
/src/directives/bindInput.ts:
--------------------------------------------------------------------------------
  1 | import {directive, AsyncDirective} from 'lit/async-directive.js';
  2 | import {nothing} from 'lit';
  3 | import type {
  4 |   ElementPart,
  5 |   DirectiveParameters,
  6 |   PartInfo,
  7 |   DirectiveResult,
  8 |   DirectiveClass
  9 | } from 'lit/directive.js';
 10 | import {PartType} from 'lit/directive.js';
 11 | 
 12 | type PropertyLike = string | symbol | number;
 13 | 
 14 | /**
 15 |  * Determines if a target is an element
 16 |  * @param {EventTarget} target Target to test
 17 |  * @return {boolean}
 18 |  */
 19 | function isElement(target: EventTarget): target is Element {
 20 |   return (target as Node).nodeType === Node.ELEMENT_NODE;
 21 | }
 22 | 
 23 | /**
 24 |  * Determines if a target is an input element
 25 |  * @param {EventTarget} target Target to test
 26 |  * @return {boolean}
 27 |  */
 28 | function isInputElement(target: EventTarget): target is HTMLInputElement {
 29 |   return isElement(target) && target.nodeName === 'INPUT';
 30 | }
 31 | 
 32 | /**
 33 |  * Determines if a target is a select element
 34 |  * @param {EventTarget} target Target to test
 35 |  * @return {boolean}
 36 |  */
 37 | function isSelectElement(target: EventTarget): target is HTMLSelectElement {
 38 |   return isElement(target) && target.nodeName === 'SELECT';
 39 | }
 40 | 
 41 | /**
 42 |  * Determines if a target is a textarea element
 43 |  * @param {EventTarget} target Target to test
 44 |  * @return {boolean}
 45 |  */
 46 | function isTextAreaElement(target: EventTarget): target is HTMLTextAreaElement {
 47 |   return isElement(target) && target.nodeName === 'TEXTAREA';
 48 | }
 49 | 
 50 | /**
 51 |  * Tracks the value of a form control and propagates data two-way to/from a
 52 |  * given host property.
 53 |  */
 54 | class BindInputDirective extends AsyncDirective {
 55 |   private __element?: Element;
 56 |   private __prop?: PropertyLike;
 57 |   private __host: unknown | undefined = undefined;
 58 |   private __lastValue: unknown = undefined;
 59 |   private __isAttribute: boolean;
 60 | 
 61 |   /** @inheritdoc */
 62 |   public constructor(partInfo: PartInfo) {
 63 |     super(partInfo);
 64 | 
 65 |     if (
 66 |       partInfo.type !== PartType.ELEMENT &&
 67 |       partInfo.type !== PartType.ATTRIBUTE &&
 68 |       partInfo.type !== PartType.PROPERTY
 69 |     ) {
 70 |       throw new Error(
 71 |         'The `bindInput` directive must be used in an element or ' +
 72 |           'attribute binding'
 73 |       );
 74 |     }
 75 | 
 76 |     this.__isAttribute =
 77 |       partInfo.type === PartType.ATTRIBUTE ||
 78 |       partInfo.type === PartType.PROPERTY;
 79 |   }
 80 | 
 81 |   /** @inheritdoc */
 82 |   public render(host: unknown, prop: PropertyLike): unknown {
 83 |     if (this.__isAttribute) {
 84 |       return this.__computeValueFromHost(host, prop);
 85 |     }
 86 |     return nothing;
 87 |   }
 88 | 
 89 |   /** @inheritdoc */
 90 |   public override update(
 91 |     part: ElementPart,
 92 |     [host, prop]: DirectiveParameters<this>
 93 |   ): unknown {
 94 |     if (part.element !== this.__element) {
 95 |       this.__setElement(part.element);
 96 |     }
 97 | 
 98 |     if (prop !== this.__prop) {
 99 |       this.__prop = prop;
100 |     }
101 | 
102 |     if (host !== this.__host) {
103 |       this.__host = host;
104 |     }
105 | 
106 |     if (host && !this.__isAttribute) {
107 |       this.__updateValueFromHost(host);
108 |     }
109 | 
110 |     return this.render(host, prop);
111 |   }
112 | 
113 |   /**
114 |    * Gets the value of the property from the host
115 |    * @param {unknown} host Host to retrieve value from
116 |    * @param {string|symbol|number} prop Property to retrieve
117 |    * @return {unknown}
118 |    */
119 |   private __computeValueFromHost(host: unknown, prop: PropertyLike): unknown {
120 |     if (typeof host !== 'object' || host === null || !(prop in host)) {
121 |       return undefined;
122 |     }
123 | 
124 |     return (host as Record<PropertyLike, unknown>)[prop];
125 |   }
126 | 
127 |   /**
128 |    * Updates the value based on the host's current value for the given
129 |    * property
130 |    * @param {unknown} host Host to retrieve value from
131 |    * @return {void}
132 |    */
133 |   private __updateValueFromHost(host: unknown): void {
134 |     if (!this.__prop || !this.__element) {
135 |       return;
136 |     }
137 | 
138 |     const value = this.__computeValueFromHost(host, this.__prop);
139 |     const element = this.__element;
140 | 
141 |     if (value === this.__lastValue) {
142 |       return;
143 |     }
144 | 
145 |     this.__lastValue = value;
146 | 
147 |     if (isInputElement(element)) {
148 |       if (element.type === 'checkbox') {
149 |         element.checked = value === true;
150 |       } else {
151 |         element.value = String(value ?? '');
152 |       }
153 |     } else if (isSelectElement(element)) {
154 |       if (element.multiple) {
155 |         const valuesArray = Array.isArray(value) ? value : [value];
156 | 
157 |         for (const opt of element.options) {
158 |           if (valuesArray.includes(opt.value)) {
159 |             opt.selected = true;
160 |           }
161 |         }
162 |       } else {
163 |         element.value = String(value ?? '');
164 |       }
165 |     } else if (isTextAreaElement(element)) {
166 |       element.value = String(value ?? '');
167 |     } else if ('value' in element) {
168 |       element.value = value;
169 |     }
170 |   }
171 | 
172 |   /**
173 |    * Sets the element and its handlers
174 |    * @param {Element} element Element to set
175 |    * @return {void}
176 |    */
177 |   private __setElement(element: Element): void {
178 |     if (this.__element) {
179 |       this.__removeListenersFromElement(this.__element);
180 |     }
181 | 
182 |     this.__element = element;
183 | 
184 |     this.__addListenersToElement(element);
185 |   }
186 | 
187 |   /**
188 |    * Removes any associated listeners from the given element
189 |    * @param {Element} element Element to remove listeners from
190 |    * @return {void}
191 |    */
192 |   private __removeListenersFromElement(element: Element): void {
193 |     element.removeEventListener('change', this.__onChange);
194 |     element.removeEventListener('input', this.__onInput);
195 |   }
196 | 
197 |   /**
198 |    * Adds any associated listeners to the given element
199 |    * @param {Element} element Element to add listeners to
200 |    * @return {void}
201 |    */
202 |   private __addListenersToElement(element: Element): void {
203 |     element.addEventListener('change', this.__onChange);
204 |     element.addEventListener('input', this.__onInput);
205 |   }
206 | 
207 |   /**
208 |    * Fired when the change event occurs
209 |    * @param {Event} ev Event fired
210 |    * @return {void}
211 |    */
212 |   private __onChange = (ev: Event): void => {
213 |     const target = ev.currentTarget;
214 | 
215 |     if (target !== this.__element) {
216 |       return;
217 |     }
218 | 
219 |     this.__updateValueFromElement(this.__element);
220 |   };
221 | 
222 |   /**
223 |    * Retrieves the value of a given element
224 |    * @param {Element} element Element to retrieve value from
225 |    * @return {unknown}
226 |    */
227 |   private __getValueFromElement(element: Element): unknown {
228 |     let value: unknown = undefined;
229 | 
230 |     if (isInputElement(element)) {
231 |       if (element.type === 'checkbox') {
232 |         value = element.checked === true;
233 |       } else {
234 |         value = element.value;
235 |       }
236 |     } else if (isSelectElement(element)) {
237 |       if (element.multiple) {
238 |         value = [...element.selectedOptions].map((opt) => opt.value);
239 |       } else {
240 |         value = element.value;
241 |       }
242 |     } else if (isTextAreaElement(element)) {
243 |       value = element.value;
244 |     } else if ('value' in element) {
245 |       value = element.value;
246 |     }
247 | 
248 |     return value;
249 |   }
250 | 
251 |   /**
252 |    * Updates the host value from an element
253 |    * @param {Element} element Element to retrieve value from
254 |    * @return {void}
255 |    */
256 |   private __updateValueFromElement(element: Element): void {
257 |     if (!this.__prop) {
258 |       return;
259 |     }
260 | 
261 |     if (
262 |       !this.__host ||
263 |       typeof this.__host !== 'object' ||
264 |       !(this.__prop in this.__host)
265 |     ) {
266 |       return;
267 |     }
268 | 
269 |     const value = this.__getValueFromElement(element);
270 | 
271 |     this.__lastValue = value;
272 | 
273 |     (this.__host as Record<PropertyLike, unknown>)[this.__prop] = value;
274 |   }
275 | 
276 |   /**
277 |    * Fired when the input event occurs
278 |    * @param {Event} ev Event fired
279 |    * @return {void}
280 |    */
281 |   private __onInput = (ev: Event): void => {
282 |     const target = ev.currentTarget;
283 | 
284 |     if (target !== this.__element) {
285 |       return;
286 |     }
287 | 
288 |     this.__updateValueFromElement(this.__element);
289 |   };
290 | 
291 |   /** @inheritdoc */
292 |   public override reconnected(): void {
293 |     if (this.__element) {
294 |       this.__addListenersToElement(this.__element);
295 |     }
296 |   }
297 | 
298 |   /** @inheritdoc */
299 |   public override disconnected(): void {
300 |     if (this.__element) {
301 |       this.__removeListenersFromElement(this.__element);
302 |     }
303 |   }
304 | }
305 | 
306 | const bindInputDirective = directive(BindInputDirective);
307 | 
308 | /**
309 |  * Two-way binds a given property to the input it is defined on.
310 |  *
311 |  * For example:
312 |  *
313 |  * ```ts
314 |  * html`
315 |  *  <input type="text" ${input(this, 'name')}>
316 |  * `;
317 |  * ```
318 |  *
319 |  * @param {T} host Host object of the property
320 |  * @param {string} key Property to bind
321 |  * @return {DirectiveResult}
322 |  */
323 | export function bindInput<T, TKey extends keyof T>(
324 |   host: T,
325 |   key: TKey
326 | ): DirectiveResult<DirectiveClass> {
327 |   return bindInputDirective(host, key);
328 | }
329 | 


--------------------------------------------------------------------------------
/src/directives/onLongPress.ts:
--------------------------------------------------------------------------------
  1 | import {ElementPart, noChange} from 'lit';
  2 | import {AsyncDirective, directive, PartType} from 'lit/async-directive.js';
  3 | import type {
  4 |   DirectiveParameters,
  5 |   DirectiveClass,
  6 |   DirectiveResult,
  7 |   PartInfo
  8 | } from 'lit/async-directive.js';
  9 | 
 10 | export type LongPressCallback = (event: PointerEvent) => void;
 11 | 
 12 | const DEFAULT_LONG_PRESS_TIMEOUT_MS: number = 1000;
 13 | 
 14 | /**
 15 |  * Calls a callback when the pointer has been held down for a specified
 16 |  * duration
 17 |  */
 18 | class LongPressDirective extends AsyncDirective {
 19 |   /** Element of the directive. */
 20 |   private __element?: Element;
 21 | 
 22 |   /**
 23 |    * Long press timeout.
 24 |    * This timeout initiates when the pointer is pressed on the
 25 |    * element. It calls user's callback unless cancel events occur
 26 |    * before time's out.
 27 |    */
 28 |   private __longPressTimer?: number;
 29 | 
 30 |   /** Time before the timeout runs out. */
 31 |   private __longPressTimeoutMs: number = DEFAULT_LONG_PRESS_TIMEOUT_MS;
 32 | 
 33 |   /** User-defined callback for long-press event */
 34 |   private __longPressCallback?: LongPressCallback;
 35 | 
 36 |   /** @inheritdoc */
 37 |   public constructor(partInfo: PartInfo) {
 38 |     super(partInfo);
 39 | 
 40 |     if (partInfo.type !== PartType.ELEMENT) {
 41 |       throw new Error(
 42 |         'The `onLongPress` directive must be used in an element binding'
 43 |       );
 44 |     }
 45 |   }
 46 | 
 47 |   /** @inheritdoc */
 48 |   public render(
 49 |     _callback: LongPressCallback,
 50 |     _callbackTimeoutMs?: number
 51 |   ): unknown {
 52 |     return noChange;
 53 |   }
 54 | 
 55 |   /** @inheritdoc */
 56 |   public override update(
 57 |     part: ElementPart,
 58 |     [callback, callbackTimeoutMs]: DirectiveParameters<this>
 59 |   ): unknown {
 60 |     if (part.element !== this.__element) {
 61 |       this.__setElement(part.element);
 62 |     }
 63 | 
 64 |     this.__longPressCallback = callback;
 65 |     this.__longPressTimeoutMs =
 66 |       callbackTimeoutMs ?? DEFAULT_LONG_PRESS_TIMEOUT_MS;
 67 | 
 68 |     return this.render(callback, callbackTimeoutMs);
 69 |   }
 70 | 
 71 |   /**
 72 |    * Sets the element and its handlers
 73 |    * @param {Element} element Element to set
 74 |    * @return {void}
 75 |    */
 76 |   private __setElement(element: Element) {
 77 |     // Detach events from previous element
 78 |     if (this.__element) {
 79 |       this.__removeListenersFromElement(this.__element);
 80 |     }
 81 |     this.__element = element;
 82 |     this.__addListenersToElement(element);
 83 |   }
 84 | 
 85 |   /**
 86 |    * Removes any associated listeners from the given element
 87 |    * @param {Element} node Element to remove listeners from
 88 |    * @return {void}
 89 |    */
 90 |   private __removeListenersFromElement(node: Element): void {
 91 |     // cast to get strongly typed events (sadtimes)
 92 |     const element = node as HTMLElement;
 93 |     element.removeEventListener('pointerdown', this.__onPointerDown);
 94 |     element.removeEventListener('pointerup', this.__onPointerUp);
 95 |     element.removeEventListener('pointerleave', this.__onPointerLeave);
 96 |   }
 97 | 
 98 |   /**
 99 |    * Adds any associated listeners to the given element
100 |    * @param {Element} node Element to add listeners to
101 |    * @return {void}
102 |    */
103 |   private __addListenersToElement(node: Element): void {
104 |     // cast to get strongly typed events (sadtimes)
105 |     const element = node as HTMLElement;
106 |     element.addEventListener('pointerdown', this.__onPointerDown);
107 |     element.addEventListener('pointerup', this.__onPointerUp);
108 |     element.addEventListener('pointerleave', this.__onPointerLeave);
109 |   }
110 | 
111 |   /**
112 |    * Fired when the pointer is down/pressed
113 |    * @param {PointerEvent} e Event fired
114 |    * @return {void}
115 |    */
116 |   private __onPointerDown = (e: PointerEvent): void => {
117 |     // TODO: When the mouse is released and long press event
118 |     // was accepted, we should find a way to cancel the @click
119 |     // event listener if it exists.
120 |     this.__initiateTimer(e);
121 |   };
122 | 
123 |   /**
124 |    * Fired when the pointer is up/released
125 |    * @return {void}
126 |    */
127 |   private __onPointerUp = (): void => {
128 |     this.__clearTimer();
129 |   };
130 | 
131 |   /**
132 |    * Fired when the pointer leaves the host
133 |    * @return {void}
134 |    */
135 |   private __onPointerLeave = (): void => {
136 |     this.__clearTimer();
137 |   };
138 | 
139 |   /**
140 |    * Start the long press timeout.
141 |    * @returns {void}
142 |    */
143 |   private __initiateTimer(e: PointerEvent): void {
144 |     this.__longPressTimer = setTimeout(() => {
145 |       if (this.__longPressCallback) {
146 |         this.__longPressCallback(e);
147 |       }
148 |     }, this.__longPressTimeoutMs);
149 |   }
150 | 
151 |   /**
152 |    * Cancel the long press timeout.
153 |    * This function is called when the user releases the mouse
154 |    * or when the mouse leaves the element.
155 |    * @return {void}
156 |    */
157 |   private __clearTimer(): void {
158 |     clearTimeout(this.__longPressTimer);
159 |   }
160 | 
161 |   /** @inheritdoc */
162 |   public override reconnected(): void {
163 |     if (this.__element) {
164 |       this.__addListenersToElement(this.__element);
165 |     }
166 |   }
167 | 
168 |   /** @inheritdoc */
169 |   public override disconnected(): void {
170 |     if (this.__element) {
171 |       this.__removeListenersFromElement(this.__element);
172 |     }
173 |   }
174 | }
175 | 
176 | const onLongPressDirective = directive(LongPressDirective);
177 | 
178 | /**
179 |  * Calls the `callback` function when the user has held their pointer down
180 |  * for the specified duration (default 1s).
181 |  *
182 |  * For example:
183 |  *
184 |  * ```ts
185 |  * html`
186 |  *  <div ${onLongPress(fn)}>Long press me!</div>
187 |  * `;
188 |  * ```
189 |  *
190 |  * @param {LongPressCallback} callback Function to call on long press
191 |  * @param {number=} callbackTimeoutMs Time to wait before considering the event
192 |  * to be a long press
193 |  * @return {DirectiveResult}
194 |  */
195 | export function onLongPress(
196 |   callback: LongPressCallback,
197 |   callbackTimeoutMs?: number
198 | ): DirectiveResult<DirectiveClass> {
199 |   return onLongPressDirective(callback, callbackTimeoutMs);
200 | }
201 | 


--------------------------------------------------------------------------------
/src/main.ts:
--------------------------------------------------------------------------------
 1 | export * from './controllers/activeElement.js';
 2 | export * from './controllers/documentVisibility.js';
 3 | export * from './controllers/elementSize.js';
 4 | export * from './controllers/elementVisibility.js';
 5 | export * from './controllers/head.js';
 6 | export * from './controllers/itemSelection.js';
 7 | export * from './controllers/keyBinding.js';
 8 | export * from './controllers/localStorage.js';
 9 | export * from './controllers/markdown.js';
10 | export * from './controllers/permissions.js';
11 | export * from './controllers/propertyHistory.js';
12 | export * from './controllers/sessionStorage.js';
13 | export * from './controllers/slot.js';
14 | export * from './controllers/windowScroll.js';
15 | export * from './directives/bindInput.js';
16 | export * from './directives/onLongPress.js';
17 | 


--------------------------------------------------------------------------------
/src/test/controllers/activeElement_test.ts:
--------------------------------------------------------------------------------
 1 | import '../util.js';
 2 | 
 3 | import {html} from 'lit';
 4 | import * as assert from 'uvu/assert';
 5 | import {ActiveElementController} from '../../main.js';
 6 | import type {TestElement} from '../util.js';
 7 | 
 8 | suite('ActiveElementController', () => {
 9 |   let element: TestElement;
10 |   let controller: ActiveElementController;
11 | 
12 |   setup(async () => {
13 |     element = document.createElement('test-element') as TestElement;
14 |     controller = new ActiveElementController(element);
15 |     element.controllers.push(controller);
16 |     element.template = () => html`${controller.activeElement?.nodeName}`;
17 |     document.body.appendChild(element);
18 |   });
19 | 
20 |   teardown(() => {
21 |     element.remove();
22 |   });
23 | 
24 |   test('initialises to current active element', () => {
25 |     assert.equal(controller.activeElement, document.activeElement);
26 |     assert.equal(element.shadowRoot!.textContent, 'BODY');
27 |   });
28 | 
29 |   test('updates active element on focus change', async () => {
30 |     const input = document.createElement('input');
31 | 
32 |     try {
33 |       document.body.appendChild(input);
34 | 
35 |       input.focus();
36 |       input.dispatchEvent(
37 |         new FocusEvent('focusin', {
38 |           bubbles: true,
39 |           composed: true
40 |         })
41 |       );
42 | 
43 |       await element.updateComplete;
44 | 
45 |       assert.equal(controller.activeElement, input);
46 |       assert.equal(element.shadowRoot!.textContent, 'INPUT');
47 | 
48 |       input.blur();
49 |       input.dispatchEvent(
50 |         new FocusEvent('focusout', {
51 |           bubbles: true,
52 |           composed: true
53 |         })
54 |       );
55 | 
56 |       await element.updateComplete;
57 | 
58 |       assert.equal(controller.activeElement, document.body);
59 |       assert.equal(element.shadowRoot!.textContent, 'BODY');
60 |     } finally {
61 |       input.remove();
62 |     }
63 |   });
64 | });
65 | 


--------------------------------------------------------------------------------
/src/test/controllers/documentVisibility_test.ts:
--------------------------------------------------------------------------------
 1 | import '../util.js';
 2 | 
 3 | import {html} from 'lit';
 4 | import * as assert from 'uvu/assert';
 5 | import {DocumentVisibilityController} from '../../main.js';
 6 | import type {TestElement} from '../util.js';
 7 | 
 8 | suite('DocumentVisibilityController', () => {
 9 |   let element: TestElement;
10 |   let controller: DocumentVisibilityController;
11 | 
12 |   setup(async () => {
13 |     element = document.createElement('test-element');
14 |     controller = new DocumentVisibilityController(element);
15 |     element.controllers.push(controller);
16 |     element.template = () => html`${controller.visible}`;
17 |     document.body.appendChild(element);
18 |   });
19 | 
20 |   teardown(() => {
21 |     element.remove();
22 |   });
23 | 
24 |   test('initialises to current visibility', () => {
25 |     assert.equal(controller.visible, true);
26 |     assert.equal(element.shadowRoot!.textContent, 'true');
27 |   });
28 | 
29 |   test('updates visibility on visibility change');
30 | });
31 | 


--------------------------------------------------------------------------------
/src/test/controllers/elementSize_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import {html} from 'lit';
  4 | import * as assert from 'uvu/assert';
  5 | import {createRef, ref} from 'lit/directives/ref.js';
  6 | import type {Ref} from 'lit/directives/ref.js';
  7 | import {ElementSizeController} from '../../main.js';
  8 | import type {TestElement} from '../util.js';
  9 | 
 10 | suite('ElementSizeController', () => {
 11 |   let element: TestElement;
 12 |   let controller: ElementSizeController;
 13 | 
 14 |   setup(() => {
 15 |     element = document.createElement('test-element');
 16 |   });
 17 | 
 18 |   teardown(() => {
 19 |     element.remove();
 20 |   });
 21 | 
 22 |   suite('host element', () => {
 23 |     setup(async () => {
 24 |       controller = new ElementSizeController(element);
 25 |       element.controllers.push(controller);
 26 |       element.template = () =>
 27 |         html`${controller.size.width}x${controller.size.height}`;
 28 |       document.body.appendChild(element);
 29 |       await element.updateComplete;
 30 | 
 31 |       element.style.width = '200px';
 32 |       element.style.height = '200px';
 33 | 
 34 |       // TODO (43081j): find a cleaner way to wait the right amount
 35 |       // of time
 36 |       await new Promise((r) => {
 37 |         requestAnimationFrame(() => {
 38 |           requestAnimationFrame(r);
 39 |         });
 40 |       });
 41 |     });
 42 | 
 43 |     test('initialises to current element size', () => {
 44 |       assert.equal(controller.size, {width: 200, height: 200});
 45 |       assert.equal(element.shadowRoot!.textContent, '200x200');
 46 |     });
 47 | 
 48 |     test('reacts to resizes', async () => {
 49 |       element.style.width = '400px';
 50 |       element.style.height = '400px';
 51 | 
 52 |       // TODO (43081j): find a cleaner way to wait the right amount
 53 |       // of time
 54 |       await new Promise((r) => {
 55 |         requestAnimationFrame(() => {
 56 |           requestAnimationFrame(r);
 57 |         });
 58 |       });
 59 | 
 60 |       assert.equal(controller.size, {width: 400, height: 400});
 61 |       assert.equal(element.shadowRoot!.textContent, '400x400');
 62 |     });
 63 |   });
 64 | 
 65 |   suite('custom ref', () => {
 66 |     let elementRef: Ref<HTMLElement>;
 67 | 
 68 |     setup(async () => {
 69 |       elementRef = createRef<HTMLElement>();
 70 |       controller = new ElementSizeController(element, 'content', elementRef);
 71 |       element.controllers.push(controller);
 72 |       element.template = () => html` <div ${ref(elementRef)}>
 73 |         ${controller.size.width}x${controller.size.height}
 74 |       </div>`;
 75 |       document.body.appendChild(element);
 76 |       await element.updateComplete;
 77 | 
 78 |       const child = element.shadowRoot!.querySelector('div')!;
 79 |       child.style.width = '200px';
 80 |       child.style.height = '200px';
 81 | 
 82 |       // TODO (43081j): find a cleaner way to wait the right amount
 83 |       // of time
 84 |       await new Promise((r) => {
 85 |         requestAnimationFrame(() => {
 86 |           requestAnimationFrame(r);
 87 |         });
 88 |       });
 89 |     });
 90 | 
 91 |     test('initialises to current element size', () => {
 92 |       assert.equal(controller.size, {width: 200, height: 200});
 93 |       assert.equal(element.shadowRoot!.textContent!.trim(), '200x200');
 94 |     });
 95 | 
 96 |     test('reacts to resizes', async () => {
 97 |       elementRef.value!.style.width = '400px';
 98 |       elementRef.value!.style.height = '400px';
 99 | 
100 |       // TODO (43081j): find a cleaner way to wait the right amount
101 |       // of time
102 |       await new Promise((r) => {
103 |         requestAnimationFrame(() => {
104 |           requestAnimationFrame(r);
105 |         });
106 |       });
107 | 
108 |       assert.equal(controller.size, {width: 400, height: 400});
109 |       assert.equal(element.shadowRoot!.textContent!.trim(), '400x400');
110 |     });
111 |   });
112 | });
113 | 


--------------------------------------------------------------------------------
/src/test/controllers/elementVisibility_test.ts:
--------------------------------------------------------------------------------
 1 | import '../util.js';
 2 | 
 3 | import {html} from 'lit';
 4 | import * as assert from 'uvu/assert';
 5 | import {ElementVisibilityController} from '../../main.js';
 6 | import type {TestElement} from '../util.js';
 7 | 
 8 | suite('ElementVisibilityController', () => {
 9 |   let element: TestElement;
10 |   let controller: ElementVisibilityController;
11 | 
12 |   setup(async () => {
13 |     element = document.createElement('test-element') as TestElement;
14 |     controller = new ElementVisibilityController(element);
15 |     element.controllers.push(controller);
16 |     element.template = () => html`Visible: ${controller.visible}`;
17 |     document.body.appendChild(element);
18 |     await element.updateComplete;
19 |   });
20 | 
21 |   teardown(() => {
22 |     element.remove();
23 |   });
24 | 
25 |   test('initialises to the current visibility', () => {
26 |     assert.equal(controller.visible, true);
27 |     assert.equal(element.shadowRoot!.textContent, 'Visible: true');
28 |   });
29 | 
30 |   test('observes visibility changes', async () => {
31 |     const bigElement = document.createElement('div');
32 |     bigElement.style.height = '6000px';
33 |     bigElement.style.width = '10px';
34 | 
35 |     try {
36 |       document.body.appendChild(bigElement);
37 | 
38 |       window.scrollBy(0, 100);
39 | 
40 |       // TODO (43081j): find a better way to wait for the
41 |       // observer to trigger
42 |       await new Promise((res) => {
43 |         requestAnimationFrame(() => {
44 |           requestAnimationFrame(res);
45 |         });
46 |       });
47 | 
48 |       assert.equal(controller.visible, false);
49 |       assert.equal(element.shadowRoot!.textContent, 'Visible: false');
50 |     } finally {
51 |       bigElement.remove();
52 |     }
53 |   });
54 | });
55 | 


--------------------------------------------------------------------------------
/src/test/controllers/head_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import * as assert from 'uvu/assert';
  4 | import {html} from 'lit';
  5 | import {HeadController} from '../../main.js';
  6 | import type {TestElement} from '../util.js';
  7 | 
  8 | suite('HeadController', () => {
  9 |   let element: TestElement;
 10 |   let controller: HeadController;
 11 | 
 12 |   teardown(() => {
 13 |     element.remove();
 14 |     for (const attr of document.body.attributes) {
 15 |       document.body.removeAttribute(attr.name);
 16 |     }
 17 |     for (const attr of document.documentElement.attributes) {
 18 |       document.documentElement.removeAttribute(attr.name);
 19 |     }
 20 |     controller.removeRenderedElements();
 21 |   });
 22 | 
 23 |   suite('default', () => {
 24 |     setup(async () => {
 25 |       element = document.createElement('test-element') as TestElement;
 26 |       controller = new HeadController(element);
 27 |       element.controllers.push(controller);
 28 |       document.body.appendChild(element);
 29 |     });
 30 | 
 31 |     test('initialises to current active element', () => {
 32 |       assert.equal(controller.defaultTitle, undefined);
 33 |       assert.equal(controller.titleTemplate, undefined);
 34 |     });
 35 | 
 36 |     suite('setTitle', () => {
 37 |       test('sets the document title', () => {
 38 |         controller.setTitle('floof');
 39 |         assert.is(document.title, 'floof');
 40 |       });
 41 | 
 42 |       test('sets the templated title if a template exists', () => {
 43 |         controller.titleTemplate = 'foo - %s';
 44 |         controller.setTitle('beans');
 45 |         assert.is(document.title, 'foo - beans');
 46 |       });
 47 |     });
 48 | 
 49 |     suite('updateBodyAttr', () => {
 50 |       test('updates attributes on body tag', () => {
 51 |         controller.updateBodyAttr({
 52 |           'data-foo': 'bar'
 53 |         });
 54 |         assert.is(document.body.getAttribute('data-foo'), 'bar');
 55 |       });
 56 | 
 57 |       test('removes null attributes from tag', () => {
 58 |         document.body.setAttribute('data-foo', 'bar');
 59 |         controller.updateBodyAttr({
 60 |           'data-foo': null
 61 |         });
 62 |         assert.is(document.body.hasAttribute('data-foo'), false);
 63 |       });
 64 |     });
 65 | 
 66 |     suite('updateHtmlAttr', () => {
 67 |       test('updates attributes on tag', () => {
 68 |         controller.updateHtmlAttr({
 69 |           'data-foo': 'bar'
 70 |         });
 71 |         assert.is(document.documentElement.getAttribute('data-foo'), 'bar');
 72 |       });
 73 | 
 74 |       test('removes null attributes from tag', () => {
 75 |         document.documentElement.setAttribute('data-foo', 'bar');
 76 |         controller.updateHtmlAttr({
 77 |           'data-foo': null
 78 |         });
 79 |         assert.is(document.documentElement.hasAttribute('data-foo'), false);
 80 |       });
 81 |     });
 82 | 
 83 |     suite('update', () => {
 84 |       test('renders title element', () => {
 85 |         controller.update(html`<title>Foo</title>`);
 86 |         const titles = document.head.querySelectorAll('title');
 87 | 
 88 |         assert.is(titles.length, 1);
 89 |         assert.is(titles[0]!.outerHTML, `<title>Foo</title>`);
 90 |         assert.is(document.title, 'Foo');
 91 |       });
 92 | 
 93 |       test('renders base element', () => {
 94 |         controller.update(html`<base href="foo">`);
 95 |         const nodes = document.head.querySelectorAll('base');
 96 | 
 97 |         assert.is(nodes.length, 1);
 98 |         assert.is(nodes[0]!.outerHTML, `<base href="foo">`);
 99 |       });
100 | 
101 |       test('renders link element', () => {
102 |         controller.update(html`<link rel="stylesheet" href="foo.css">`);
103 |         const nodes = document.head.querySelectorAll('link[href="foo.css"]');
104 | 
105 |         assert.is(nodes.length, 1);
106 |         assert.is(
107 |           nodes[0]!.outerHTML,
108 |           `<link rel="stylesheet" href="foo.css">`
109 |         );
110 |       });
111 | 
112 |       test('renders script element', () => {
113 |         controller.update(html`
114 |           <script type="module" id="foo">
115 |             const foo = 5;
116 |           </script>
117 |         `);
118 |         const nodes = document.head.querySelectorAll('script#foo');
119 | 
120 |         assert.is(nodes.length, 1);
121 |         assert.is(
122 |           nodes[0]!.outerHTML,
123 |           `<script type="module" id="foo">
124 |             const foo = 5;
125 |           </script>`
126 |         );
127 |       });
128 | 
129 |       test('renders noscript element', () => {
130 |         controller.update(html`
131 |           <noscript id="foo">
132 |             <meta name="waffles">
133 |           </noscript>
134 |         `);
135 |         const nodes = document.head.querySelectorAll('noscript#foo');
136 | 
137 |         assert.is(nodes.length, 1);
138 |         assert.is(
139 |           nodes[0]!.outerHTML,
140 |           `<noscript id="foo">
141 |             <meta name="waffles">
142 |           </noscript>`
143 |         );
144 |       });
145 | 
146 |       test('renders style element', () => {
147 |         controller.update(html`
148 |           <style type="text/css" id="foo">
149 |             .foo {
150 |               color: hotpink;
151 |             }
152 |           </style>
153 |         `);
154 |         const nodes = document.head.querySelectorAll('style#foo');
155 | 
156 |         assert.is(nodes.length, 1);
157 |         assert.is(
158 |           nodes[0]!.outerHTML,
159 |           `<style type="text/css" id="foo">
160 |             .foo {
161 |               color: hotpink;
162 |             }
163 |           </style>`
164 |         );
165 |       });
166 | 
167 |       test('renders meta element', () => {
168 |         controller.update(html`<meta name="waffles" id="foo">`);
169 |         const nodes = document.head.querySelectorAll('meta#foo');
170 | 
171 |         assert.is(nodes.length, 1);
172 |         assert.is(nodes[0]!.outerHTML, `<meta name="waffles" id="foo">`);
173 |       });
174 | 
175 |       test('updates already rendered elements', () => {
176 |         controller.update(html`<meta name="waffles" id="foo">`);
177 |         controller.update(html`<meta name="wuffles" id="foo">`);
178 | 
179 |         const nodes = document.head.querySelectorAll('meta#foo');
180 | 
181 |         assert.is(nodes.length, 1);
182 |         assert.is(nodes[0]!.outerHTML, `<meta name="wuffles" id="foo">`);
183 |       });
184 | 
185 |       test('replaces title element if exists', () => {
186 |         controller.update(html`<title>Foo</title>`);
187 |         controller.update(html`<title>Bar</title>`);
188 |         const titles = document.head.querySelectorAll('title');
189 | 
190 |         assert.is(titles.length, 1);
191 |         assert.is(titles[0]!.textContent, 'Bar');
192 |         assert.is(document.title, 'Bar');
193 |       });
194 | 
195 |       test('replaces base element if exists', () => {
196 |         controller.update(html`<base href="foo">`);
197 |         controller.update(html`<base href="bar">`);
198 |         const nodes = document.head.querySelectorAll('base');
199 | 
200 |         assert.is(nodes.length, 1);
201 |         assert.is(nodes[0]!.getAttribute('href'), 'bar');
202 |       });
203 | 
204 |       test('renders multiple elements', () => {
205 |         controller.update(html`
206 |           <meta name="waffles" id="foo">
207 |           <meta name="wuffles" id="bar">
208 |         `);
209 |         const nodes = document.head.querySelectorAll('meta#foo, meta#bar');
210 | 
211 |         assert.is(nodes.length, 2);
212 |         assert.is(nodes[0]!.outerHTML, `<meta name="waffles" id="foo">`);
213 |         assert.is(nodes[1]!.outerHTML, `<meta name="wuffles" id="bar">`);
214 |       });
215 |     });
216 | 
217 |     suite('removeRenderedElements', () => {
218 |       test('removes all rendered elements', () => {
219 |         controller.update(html`
220 |           <meta name="waffles" id="foo">
221 |           <meta name="wuffles" id="bar">
222 |         `);
223 | 
224 |         controller.removeRenderedElements();
225 | 
226 |         const nodes = document.head.querySelectorAll('meta#foo, meta#bar');
227 | 
228 |         assert.is(nodes.length, 0);
229 |       });
230 |     });
231 |   });
232 | 
233 |   suite('with default title', () => {
234 |     setup(async () => {
235 |       element = document.createElement('test-element') as TestElement;
236 |       controller = new HeadController(element);
237 |       controller.defaultTitle = 'bleep bloop';
238 |       element.controllers.push(controller);
239 |       document.body.appendChild(element);
240 |     });
241 | 
242 |     test('sets the document title to the default', () => {
243 |       assert.equal(controller.defaultTitle, 'bleep bloop');
244 |       assert.equal(document.title, 'bleep bloop');
245 |     });
246 | 
247 |     test('sets the document title back to default when removing title', () => {
248 |       controller.update(html`<title>Foo</title>`);
249 | 
250 |       assert.is(document.title, 'Foo');
251 | 
252 |       controller.removeRenderedElements();
253 | 
254 |       assert.is(document.title, 'bleep bloop');
255 |     });
256 |   });
257 | });
258 | 


--------------------------------------------------------------------------------
/src/test/controllers/itemSelection_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import {html, ReactiveController} from 'lit';
  4 | import * as assert from 'uvu/assert';
  5 | import {ItemSelectionController} from '../../main.js';
  6 | import type {TestElement} from '../util.js';
  7 | 
  8 | suite('ItemSelectionController', () => {
  9 |   let element: TestElement;
 10 |   let controller: ItemSelectionController<string>;
 11 |   let items: string[];
 12 | 
 13 |   setup(async () => {
 14 |     items = ['a', 'b', 'c'];
 15 |     element = document.createElement('test-element') as TestElement;
 16 |     element.template = () => html`Selected: ${controller.selectedItems}`;
 17 |   });
 18 | 
 19 |   teardown(() => {
 20 |     element.remove();
 21 |   });
 22 | 
 23 |   suite('single select', () => {
 24 |     setup(async () => {
 25 |       controller = new ItemSelectionController<string>(element, items);
 26 |       element.controllers.push(controller as ReactiveController);
 27 |       document.body.appendChild(element);
 28 |     });
 29 | 
 30 |     test('initialises to no selection', () => {
 31 |       assert.is(controller.selectedItems.length, 0);
 32 |       assert.is(controller.items, items);
 33 |     });
 34 | 
 35 |     suite('next()', () => {
 36 |       test('selects the next item', async () => {
 37 |         controller.select('a');
 38 |         controller.next();
 39 |         await element.updateComplete;
 40 |         assert.equal(controller.selectedItems, ['b']);
 41 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
 42 |       });
 43 |     });
 44 | 
 45 |     suite('prev()', () => {
 46 |       test('selects the previous item', async () => {
 47 |         controller.select('c');
 48 |         controller.prev();
 49 |         await element.updateComplete;
 50 |         assert.equal(controller.selectedItems, ['b']);
 51 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
 52 |       });
 53 |     });
 54 | 
 55 |     suite('selectByOffset()', () => {
 56 |       test('selects first item if out-of-bounds negative offset', async () => {
 57 |         controller.select('a');
 58 |         controller.selectByOffset(-1);
 59 |         await element.updateComplete;
 60 |         assert.equal(controller.selectedItems, ['a']);
 61 |         assert.equal(element.shadowRoot!.textContent, 'Selected: a');
 62 |       });
 63 | 
 64 |       test('selects last item if out-of-bounds positive offset', async () => {
 65 |         controller.select('c');
 66 |         controller.selectByOffset(1);
 67 |         await element.updateComplete;
 68 |         assert.equal(controller.selectedItems, ['c']);
 69 |         assert.equal(element.shadowRoot!.textContent, 'Selected: c');
 70 |       });
 71 | 
 72 |       test('selects first item if no selection', async () => {
 73 |         controller.selectByOffset(1);
 74 |         await element.updateComplete;
 75 |         assert.equal(controller.selectedItems, ['a']);
 76 |         assert.equal(element.shadowRoot!.textContent, 'Selected: a');
 77 |       });
 78 |     });
 79 | 
 80 |     suite('selectByIndex()', () => {
 81 |       test('selects the item at the given index', async () => {
 82 |         controller.selectByIndex(1);
 83 |         await element.updateComplete;
 84 |         assert.equal(controller.selectedItems, ['b']);
 85 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
 86 |       });
 87 |     });
 88 | 
 89 |     suite('select()', () => {
 90 |       test('selects the given item', async () => {
 91 |         controller.select('b');
 92 |         await element.updateComplete;
 93 |         assert.equal(controller.selectedItems, ['b']);
 94 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
 95 |       });
 96 |     });
 97 | 
 98 |     suite('deselectAll()', () => {
 99 |       test('deselects all items', async () => {
100 |         controller.select('b');
101 |         controller.deselectAll();
102 |         await element.updateComplete;
103 |         assert.equal(controller.selectedItems, []);
104 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
105 |       });
106 |     });
107 | 
108 |     suite('selectAll', () => {
109 |       test('throws an error', async () => {
110 |         try {
111 |           controller.selectAll();
112 |           assert.unreachable();
113 |         } catch (err) {
114 |           assert.equal(
115 |             (err as Error).message,
116 |             'selectAll() cannot be used when in single-select mode'
117 |           );
118 |         }
119 |       });
120 |     });
121 | 
122 |     suite('deselectByIndex()', () => {
123 |       test('deselects the item at the given index', async () => {
124 |         controller.select('b');
125 |         controller.deselectByIndex(1);
126 |         await element.updateComplete;
127 |         assert.equal(controller.selectedItems, []);
128 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
129 |       });
130 |     });
131 | 
132 |     suite('deselect()', () => {
133 |       test('deselects the given item', async () => {
134 |         controller.select('b');
135 |         controller.deselect('b');
136 |         await element.updateComplete;
137 |         assert.equal(controller.selectedItems, []);
138 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
139 |       });
140 |     });
141 | 
142 |     suite('toggleByIndex()', () => {
143 |       test('throws if index out of range (lower bound)', () => {
144 |         try {
145 |           controller.toggleByIndex(-1);
146 |           assert.unreachable();
147 |         } catch (err) {
148 |           assert.equal((err as Error).message, 'Index cannot be below 0');
149 |         }
150 |       });
151 | 
152 |       test('throws if index out of range (upper bound)', () => {
153 |         try {
154 |           controller.toggleByIndex(10);
155 |           assert.unreachable();
156 |         } catch (err) {
157 |           assert.equal(
158 |             (err as Error).message,
159 |             'Index cannot be greater than size of items array'
160 |           );
161 |         }
162 |       });
163 | 
164 |       test('selects a currently deselected item', async () => {
165 |         controller.toggleByIndex(1);
166 |         await element.updateComplete;
167 |         assert.equal(controller.selectedItems, ['b']);
168 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
169 |       });
170 | 
171 |       test('deselects a currently selected item', async () => {
172 |         controller.select('b');
173 |         controller.toggleByIndex(1);
174 |         await element.updateComplete;
175 |         assert.equal(controller.selectedItems, []);
176 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
177 |       });
178 | 
179 |       test('can force select', async () => {
180 |         controller.toggleByIndex(1, true);
181 |         await element.updateComplete;
182 |         assert.equal(controller.selectedItems, ['b']);
183 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
184 |       });
185 | 
186 |       test('forcing select of already selected item', async () => {
187 |         controller.select('b');
188 |         controller.toggleByIndex(1, true);
189 |         await element.updateComplete;
190 |         assert.equal(controller.selectedItems, ['b']);
191 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
192 |       });
193 | 
194 |       test('can force deselect', async () => {
195 |         controller.select('b');
196 |         controller.toggleByIndex(1, false);
197 |         await element.updateComplete;
198 |         assert.equal(controller.selectedItems, []);
199 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
200 |       });
201 | 
202 |       test('forcing deselect of already deselected item', async () => {
203 |         controller.toggleByIndex(1, false);
204 |         await element.updateComplete;
205 |         assert.equal(controller.selectedItems, []);
206 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
207 |       });
208 |     });
209 | 
210 |     suite('toggle()', () => {
211 |       test('throws if item does not exist', () => {
212 |         try {
213 |           controller.toggle('non-existent');
214 |           assert.unreachable();
215 |         } catch (err) {
216 |           assert.equal((err as Error).message, 'Item was not in items array');
217 |         }
218 |       });
219 | 
220 |       test('toggles specified item', async () => {
221 |         controller.toggle('b');
222 |         await element.updateComplete;
223 |         assert.equal(controller.selectedItems, ['b']);
224 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
225 | 
226 |         controller.toggle('b');
227 |         await element.updateComplete;
228 |         assert.equal(controller.selectedItems, []);
229 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
230 |       });
231 | 
232 |       test('can force select', async () => {
233 |         controller.toggle('b', true);
234 |         await element.updateComplete;
235 |         assert.equal(controller.selectedItems, ['b']);
236 |         assert.equal(element.shadowRoot!.textContent, 'Selected: b');
237 |       });
238 | 
239 |       test('can force deselect', async () => {
240 |         controller.select('b');
241 |         controller.toggle('b', false);
242 |         await element.updateComplete;
243 |         assert.equal(controller.selectedItems, []);
244 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
245 |       });
246 |     });
247 |   });
248 | 
249 |   suite('multi select', () => {
250 |     setup(async () => {
251 |       controller = new ItemSelectionController<string>(element, items, {
252 |         multiSelect: true
253 |       });
254 |       element.controllers.push(controller as ReactiveController);
255 |       document.body.appendChild(element);
256 |     });
257 | 
258 |     suite('select()', () => {
259 |       test('can select multiple items', async () => {
260 |         controller.select('a');
261 |         controller.select('b');
262 |         assert.equal(controller.selectedItems, ['a', 'b']);
263 |         await element.updateComplete;
264 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ab');
265 |       });
266 |     });
267 | 
268 |     suite('next()', () => {
269 |       test('throws an error', () => {
270 |         try {
271 |           controller.next();
272 |           assert.unreachable();
273 |         } catch (err) {
274 |           assert.is(
275 |             (err as Error).message,
276 |             'next() cannot be used when in multi-select mode'
277 |           );
278 |         }
279 |       });
280 |     });
281 | 
282 |     suite('prev()', () => {
283 |       test('throws an error', () => {
284 |         try {
285 |           controller.prev();
286 |           assert.unreachable();
287 |         } catch (err) {
288 |           assert.is(
289 |             (err as Error).message,
290 |             'prev() cannot be used when in multi-select mode'
291 |           );
292 |         }
293 |       });
294 |     });
295 | 
296 |     suite('selectByOffset()', () => {
297 |       test('throws an error', () => {
298 |         try {
299 |           controller.selectByOffset(1);
300 |           assert.unreachable();
301 |         } catch (err) {
302 |           assert.is(
303 |             (err as Error).message,
304 |             'selectByOffset() cannot be used when in multi-select mode'
305 |           );
306 |         }
307 |       });
308 |     });
309 | 
310 |     suite('deselectAll', () => {
311 |       test('deselects all items', async () => {
312 |         controller.select('b');
313 |         controller.select('c');
314 |         controller.deselectAll();
315 |         await element.updateComplete;
316 |         assert.equal(controller.selectedItems, []);
317 |         assert.equal(element.shadowRoot!.textContent, 'Selected: ');
318 |       });
319 |     });
320 | 
321 |     suite('selectAll', () => {
322 |       test('selects all items', async () => {
323 |         controller.selectAll();
324 |         await element.updateComplete;
325 |         assert.equal(controller.selectedItems, ['a', 'b', 'c']);
326 |         assert.equal(element.shadowRoot!.textContent, 'Selected: abc');
327 |       });
328 |     });
329 | 
330 |     suite('toggleByIndex()', () => {
331 |       test('selects a currently deselected item', async () => {
332 |         controller.toggleByIndex(1);
333 |         controller.toggleByIndex(2);
334 |         await element.updateComplete;
335 |         assert.equal(controller.selectedItems, ['b', 'c']);
336 |         assert.equal(element.shadowRoot!.textContent, 'Selected: bc');
337 |       });
338 | 
339 |       test('deselects a currently selected item', async () => {
340 |         controller.select('b');
341 |         controller.select('c');
342 |         controller.toggleByIndex(1);
343 |         await element.updateComplete;
344 |         assert.equal(controller.selectedItems, ['c']);
345 |         assert.equal(element.shadowRoot!.textContent, 'Selected: c');
346 |       });
347 |     });
348 |   });
349 | 
350 |   suite('multi select with defaultSelectedIndices', () => {
351 |     setup(async () => {
352 |       controller = new ItemSelectionController<string>(element, items, {
353 |         defaultSelectedIndices: [1, 2],
354 |         multiSelect: true
355 |       });
356 |       element.controllers.push(controller as ReactiveController);
357 |       document.body.appendChild(element);
358 |     });
359 | 
360 |     test('initialises to default selection', () => {
361 |       assert.equal(controller.selectedItems, ['b', 'c']);
362 |       assert.equal(element.shadowRoot!.textContent, 'Selected: bc');
363 |     });
364 |   });
365 | 
366 |   suite('single select with defaultSelectedIndices', () => {
367 |     setup(async () => {
368 |       controller = new ItemSelectionController<string>(element, items, {
369 |         defaultSelectedIndices: [1]
370 |       });
371 |       element.controllers.push(controller as ReactiveController);
372 |       document.body.appendChild(element);
373 |     });
374 | 
375 |     test('initialises to default selection', () => {
376 |       assert.equal(controller.selectedItems, ['b']);
377 |       assert.equal(element.shadowRoot!.textContent, 'Selected: b');
378 |     });
379 |   });
380 | 
381 |   suite('multi select with defaultSelection', () => {
382 |     setup(async () => {
383 |       controller = new ItemSelectionController<string>(element, items, {
384 |         defaultSelection: ['b', 'c'],
385 |         multiSelect: true
386 |       });
387 |       element.controllers.push(controller as ReactiveController);
388 |       document.body.appendChild(element);
389 |     });
390 | 
391 |     test('initialises to default selection', () => {
392 |       assert.equal(controller.selectedItems, ['b', 'c']);
393 |       assert.equal(element.shadowRoot!.textContent, 'Selected: bc');
394 |     });
395 |   });
396 | 
397 |   suite('single select with defaultSelection', () => {
398 |     setup(async () => {
399 |       controller = new ItemSelectionController<string>(element, items, {
400 |         defaultSelection: ['b']
401 |       });
402 |       element.controllers.push(controller as ReactiveController);
403 |       document.body.appendChild(element);
404 |     });
405 | 
406 |     test('initialises to default selection', () => {
407 |       assert.equal(controller.selectedItems, ['b']);
408 |       assert.equal(element.shadowRoot!.textContent, 'Selected: b');
409 |     });
410 |   });
411 | 
412 |   suite('with items function', () => {
413 |     setup(async () => {
414 |       const itemsFn = (): string[] => items;
415 |       controller = new ItemSelectionController<string>(element, itemsFn);
416 |       element.controllers.push(controller as ReactiveController);
417 |       document.body.appendChild(element);
418 |     });
419 | 
420 |     test('initialises to default selection', () => {
421 |       assert.is(controller.selectedItems.length, 0);
422 |       assert.is(controller.items, items);
423 |     });
424 |   });
425 | });
426 | 


--------------------------------------------------------------------------------
/src/test/controllers/keyBinding_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import * as hanbi from 'hanbi';
  4 | import {html} from 'lit';
  5 | import * as assert from 'uvu/assert';
  6 | import {createRef, ref} from 'lit/directives/ref.js';
  7 | import type {Ref} from 'lit/directives/ref.js';
  8 | import {KeyBindingController} from '../../main.js';
  9 | import type {KeyBindingHandler} from '../../main.js';
 10 | import type {TestElement} from '../util.js';
 11 | 
 12 | /**
 13 |  * Simulates a key press via keydown/keyup
 14 |  * @param {Element} node Node to emit press to
 15 |  * @param {string} key Key to press
 16 |  * @param {number=} numOfKeyDown Number of keydown events
 17 |  * @return {void}
 18 |  */
 19 | function simulateKeyPress(
 20 |   node: Element,
 21 |   key: string | string[],
 22 |   numOfKeyDown: number = 1
 23 | ): void {
 24 |   const keys = Array.isArray(key) ? key : [key];
 25 | 
 26 |   for (const k of keys) {
 27 |     for (let i = 0; i < numOfKeyDown; i++) {
 28 |       node.dispatchEvent(
 29 |         new KeyboardEvent('keydown', {
 30 |           key: k,
 31 |           bubbles: true,
 32 |           composed: true
 33 |         })
 34 |       );
 35 |     }
 36 |   }
 37 | 
 38 |   for (const k of keys) {
 39 |     node.dispatchEvent(
 40 |       new KeyboardEvent('keyup', {
 41 |         key: k,
 42 |         bubbles: true,
 43 |         composed: true
 44 |       })
 45 |     );
 46 |   }
 47 | }
 48 | 
 49 | suite('KeyBindingController', () => {
 50 |   let element: TestElement;
 51 |   let controller: KeyBindingController;
 52 | 
 53 |   setup(() => {
 54 |     element = document.createElement('test-element');
 55 |     element.setAttribute('tabindex', '-1');
 56 |   });
 57 | 
 58 |   teardown(() => {
 59 |     element.remove();
 60 |     hanbi.restore();
 61 |   });
 62 | 
 63 |   suite('host element', () => {
 64 |     setup(async () => {
 65 |       controller = new KeyBindingController(element);
 66 |       element.controllers.push(controller);
 67 |       document.body.appendChild(element);
 68 |       await element.updateComplete;
 69 |     });
 70 | 
 71 |     suite('bindKey', () => {
 72 |       test('calls function on key up', () => {
 73 |         const spy = hanbi.spy<KeyBindingHandler>();
 74 | 
 75 |         controller.bindKey('x', spy.handler);
 76 | 
 77 |         simulateKeyPress(element, 'x');
 78 |         simulateKeyPress(element, 'y');
 79 | 
 80 |         const ev = spy.firstCall!.args[0];
 81 | 
 82 |         assert.is(ev.type, 'keyup');
 83 |         assert.is(spy.callCount, 1);
 84 |       });
 85 | 
 86 |       test('calls function on key down via triggers', () => {
 87 |         const spy = hanbi.spy<KeyBindingHandler>();
 88 | 
 89 |         controller.bindKey('x', spy.handler, {triggers: ['keydown']});
 90 | 
 91 |         simulateKeyPress(element, 'x');
 92 | 
 93 |         const ev = spy.firstCall!.args[0];
 94 | 
 95 |         assert.is(ev.type, 'keydown');
 96 |         assert.is(spy.callCount, 1);
 97 |       });
 98 | 
 99 |       test('calls function on key up/down via triggers', () => {
100 |         const spy = hanbi.spy<KeyBindingHandler>();
101 | 
102 |         controller.bindKey('x', spy.handler, {triggers: ['keydown', 'keyup']});
103 | 
104 |         simulateKeyPress(element, 'x');
105 | 
106 |         const firstEv = spy.getCall(0)!.args[0];
107 |         const secondEv = spy.getCall(1)!.args[0];
108 | 
109 |         assert.is(spy.callCount, 2);
110 |         assert.is(firstEv.type, 'keydown');
111 |         assert.is(secondEv.type, 'keyup');
112 |       });
113 | 
114 |       test('calls function on first key down via triggers', () => {
115 |         const spy = hanbi.spy<KeyBindingHandler>();
116 | 
117 |         controller.bindKey('x', spy.handler, {triggers: ['firstKeyDown']});
118 | 
119 |         simulateKeyPress(element, 'x', 2);
120 | 
121 |         const ev = spy.getCall(0)!.args[0];
122 | 
123 |         assert.is(spy.callCount, 1);
124 |         assert.is(ev.type, 'keydown');
125 |       });
126 | 
127 |       test('calls function on key up/first key down via triggers', () => {
128 |         const spy = hanbi.spy<KeyBindingHandler>();
129 | 
130 |         controller.bindKey('x', spy.handler, {
131 |           triggers: ['keyup', 'firstKeyDown']
132 |         });
133 | 
134 |         simulateKeyPress(element, 'x', 2);
135 | 
136 |         const firstEv = spy.getCall(0)!.args[0];
137 |         const secondEv = spy.getCall(1)!.args[0];
138 | 
139 |         assert.is(spy.callCount, 2);
140 |         assert.is(firstEv.type, 'keydown');
141 |         assert.is(secondEv.type, 'keyup');
142 |       });
143 | 
144 |       test('accepts single key', () => {
145 |         const spy = hanbi.spy<KeyBindingHandler>();
146 | 
147 |         controller.bindKey('x', spy.handler);
148 | 
149 |         simulateKeyPress(element, 'x');
150 | 
151 |         const ev = spy.firstCall!.args[0];
152 | 
153 |         assert.is(ev.type, 'keyup');
154 |         assert.is(spy.callCount, 1);
155 |       });
156 | 
157 |       test('accepts multiple keys', () => {
158 |         const spy = hanbi.spy<KeyBindingHandler>();
159 | 
160 |         controller.bindKey(['x', 'y'], spy.handler);
161 | 
162 |         simulateKeyPress(element, ['x', 'y']);
163 | 
164 |         const ev = spy.firstCall!.args[0];
165 | 
166 |         assert.is(spy.callCount, 1);
167 |         assert.is(ev.type, 'keyup');
168 |         assert.is(ev.key, 'x');
169 |       });
170 | 
171 |       test('supports modifier keys (ctrl)', () => {
172 |         const spy = hanbi.spy<KeyBindingHandler>();
173 | 
174 |         controller.bindKey(['ctrl', 'a'], spy.handler);
175 | 
176 |         simulateKeyPress(element, ['Ctrl', 'a']);
177 | 
178 |         const ev = spy.firstCall!.args[0];
179 | 
180 |         assert.is(spy.callCount, 1);
181 |         assert.is(ev.type, 'keyup');
182 |         assert.is(ev.key, 'Ctrl');
183 |       });
184 | 
185 |       test('supports modifier keys (meta)', () => {
186 |         const spy = hanbi.spy<KeyBindingHandler>();
187 | 
188 |         controller.bindKey(['meta', 'a'], spy.handler);
189 | 
190 |         simulateKeyPress(element, ['Meta', 'a']);
191 | 
192 |         const ev = spy.firstCall!.args[0];
193 | 
194 |         assert.is(spy.callCount, 1);
195 |         assert.is(ev.type, 'keyup');
196 |         assert.is(ev.key, 'Meta');
197 |       });
198 | 
199 |       test('supports modifier keys (alt)', () => {
200 |         const spy = hanbi.spy<KeyBindingHandler>();
201 | 
202 |         controller.bindKey(['alt', 'a'], spy.handler);
203 | 
204 |         simulateKeyPress(element, ['Alt', 'a']);
205 | 
206 |         const ev = spy.firstCall!.args[0];
207 | 
208 |         assert.is(spy.callCount, 1);
209 |         assert.is(ev.type, 'keyup');
210 |         assert.is(ev.key, 'Alt');
211 |       });
212 | 
213 |       test('supports modifier keys (shift)', () => {
214 |         const spy = hanbi.spy<KeyBindingHandler>();
215 | 
216 |         controller.bindKey(['shift', 'a'], spy.handler);
217 | 
218 |         simulateKeyPress(element, ['Shift', 'a']);
219 | 
220 |         const ev = spy.firstCall!.args[0];
221 | 
222 |         assert.is(spy.callCount, 1);
223 |         assert.is(ev.type, 'keyup');
224 |         assert.is(ev.key, 'Shift');
225 |       });
226 |     });
227 | 
228 |     suite('bindFocus', () => {
229 |       test('focuses element on key up', async () => {
230 |         const divRef = createRef();
231 |         element.template = () => html`
232 |           <div ${ref(divRef)} tabindex="-1"></div>
233 |         `;
234 |         await element.updateComplete;
235 | 
236 |         controller.bindFocus('x', divRef);
237 | 
238 |         assert.is(element.shadowRoot!.activeElement, null);
239 | 
240 |         simulateKeyPress(element, 'x');
241 | 
242 |         assert.is(element.shadowRoot!.activeElement, divRef.value!);
243 |       });
244 | 
245 |       test('handles empty refs', async () => {
246 |         const divRef = createRef();
247 | 
248 |         controller.bindFocus('x', divRef);
249 | 
250 |         assert.is(element.shadowRoot!.activeElement, null);
251 | 
252 |         simulateKeyPress(element, 'x');
253 | 
254 |         assert.is(element.shadowRoot!.activeElement, null);
255 |       });
256 |     });
257 | 
258 |     suite('bindPush', () => {
259 |       test('calls function on key up/first key down', () => {
260 |         const spy = hanbi.spy<KeyBindingHandler>();
261 | 
262 |         controller.bindPush('x', spy.handler);
263 | 
264 |         simulateKeyPress(element, 'x', 2);
265 | 
266 |         const firstEv = spy.getCall(0)!.args[0];
267 |         const secondEv = spy.getCall(1)!.args[0];
268 | 
269 |         assert.is(spy.callCount, 2);
270 |         assert.is(firstEv.type, 'keydown');
271 |         assert.is(secondEv.type, 'keyup');
272 |       });
273 |     });
274 | 
275 |     test('ignores presses from textareas by default', async () => {
276 |       const spy = hanbi.spy<KeyBindingHandler>();
277 | 
278 |       controller.bindKey('x', spy.handler);
279 | 
280 |       element.template = () => html`
281 |         <textarea></textarea>
282 |       `;
283 |       await element.updateComplete;
284 | 
285 |       const node = element.shadowRoot!.querySelector('textarea')!;
286 | 
287 |       simulateKeyPress(node, 'x');
288 | 
289 |       assert.is(spy.called, false);
290 |     });
291 | 
292 |     test('ignores presses from inputs by default', async () => {
293 |       const spy = hanbi.spy<KeyBindingHandler>();
294 | 
295 |       controller.bindKey('x', spy.handler);
296 | 
297 |       element.template = () => html`
298 |         <input>
299 |       `;
300 |       await element.updateComplete;
301 | 
302 |       const node = element.shadowRoot!.querySelector('input')!;
303 | 
304 |       simulateKeyPress(node, 'x');
305 | 
306 |       assert.is(spy.called, false);
307 |     });
308 | 
309 |     test('ignores presses from selects by default', async () => {
310 |       const spy = hanbi.spy<KeyBindingHandler>();
311 | 
312 |       controller.bindKey('x', spy.handler);
313 | 
314 |       element.template = () => html`
315 |         <select></select>
316 |       `;
317 |       await element.updateComplete;
318 | 
319 |       const node = element.shadowRoot!.querySelector('select')!;
320 | 
321 |       simulateKeyPress(node, 'x');
322 | 
323 |       assert.is(spy.called, false);
324 |     });
325 |   });
326 | 
327 |   suite('options.ignoredElements', () => {
328 |     setup(async () => {
329 |       controller = new KeyBindingController(element, null, {
330 |         ignoredElements: ['span', '.foo']
331 |       });
332 |       element.controllers.push(controller);
333 |       document.body.appendChild(element);
334 |       await element.updateComplete;
335 |     });
336 | 
337 |     test('ignores presses from named tags', async () => {
338 |       const spy = hanbi.spy<KeyBindingHandler>();
339 | 
340 |       controller.bindKey('x', spy.handler);
341 | 
342 |       element.template = () => html`
343 |         <span></span>
344 |       `;
345 |       await element.updateComplete;
346 | 
347 |       const node = element.shadowRoot!.querySelector('span')!;
348 | 
349 |       simulateKeyPress(node, 'x');
350 | 
351 |       assert.is(spy.called, false);
352 |     });
353 | 
354 |     test('ignores presses from tags by selector', async () => {
355 |       const spy = hanbi.spy<KeyBindingHandler>();
356 | 
357 |       controller.bindKey('x', spy.handler);
358 | 
359 |       element.template = () => html`
360 |         <div class="foo"></div>
361 |       `;
362 |       await element.updateComplete;
363 | 
364 |       const node = element.shadowRoot!.querySelector('div')!;
365 | 
366 |       simulateKeyPress(node, 'x');
367 | 
368 |       assert.is(spy.called, false);
369 |     });
370 |   });
371 | 
372 |   suite('custom ref', () => {
373 |     let elementRef: Ref<HTMLElement>;
374 | 
375 |     setup(async () => {
376 |       elementRef = createRef<HTMLElement>();
377 |       controller = new KeyBindingController(element, elementRef);
378 |       element.controllers.push(controller);
379 |       element.template = () => html`
380 |         <div ${ref(elementRef)} tabindex="-1">
381 |           Hello.
382 |         </div>
383 |         <span></span>`;
384 |       document.body.appendChild(element);
385 |       await element.updateComplete;
386 |     });
387 | 
388 |     test('calls function on key press in element', async () => {
389 |       const spy = hanbi.spy<KeyBindingHandler>();
390 | 
391 |       controller.bindKey('x', spy.handler);
392 | 
393 |       simulateKeyPress(elementRef.value!, 'x');
394 | 
395 |       assert.is(spy.called, true);
396 | 
397 |       const ev = spy.firstCall!.args[0];
398 | 
399 |       assert.is(ev.type, 'keyup');
400 |       assert.is(spy.callCount, 1);
401 |     });
402 | 
403 |     test('ignores presses from unrelated elements', async () => {
404 |       const spy = hanbi.spy<KeyBindingHandler>();
405 | 
406 |       controller.bindKey('x', spy.handler);
407 | 
408 |       const node = element.shadowRoot!.querySelector('span')!;
409 | 
410 |       simulateKeyPress(node, 'x');
411 | 
412 |       assert.is(spy.called, false);
413 |     });
414 |   });
415 | });
416 | 


--------------------------------------------------------------------------------
/src/test/controllers/localStorage_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import {html} from 'lit';
  4 | import * as assert from 'uvu/assert';
  5 | import {LocalStorageController} from '../../main.js';
  6 | import type {TestElement} from '../util.js';
  7 | 
  8 | suite('LocalStorageController', () => {
  9 |   let element: TestElement;
 10 |   let controller: LocalStorageController<[number, number]>;
 11 | 
 12 |   teardown(() => {
 13 |     element.remove();
 14 |     window.localStorage.removeItem('test-key');
 15 |   });
 16 | 
 17 |   suite('default', () => {
 18 |     setup(async () => {
 19 |       element = document.createElement('test-element') as TestElement;
 20 |       controller = new LocalStorageController(element, 'test-key');
 21 |       element.controllers.push(controller);
 22 |       element.template = () => html`${JSON.stringify(controller.value)}`;
 23 |       document.body.appendChild(element);
 24 |     });
 25 | 
 26 |     test('initialises to undefined', () => {
 27 |       assert.equal(controller.value, undefined);
 28 |       assert.equal(element.shadowRoot!.textContent, '');
 29 |     });
 30 | 
 31 |     suite('set value', () => {
 32 |       test('sets value in local storage', async () => {
 33 |         controller.value = [0, 0];
 34 |         await element.updateComplete;
 35 | 
 36 |         const storageValue = window.localStorage.getItem('test-key');
 37 | 
 38 |         assert.equal(controller.value, [0, 0]);
 39 |         assert.equal(element.shadowRoot!.textContent, '[0,0]');
 40 |         assert.is(storageValue, '[0,0]');
 41 |       });
 42 | 
 43 |       test('removes from storage if value undefined', async () => {
 44 |         controller.value = [0, 0];
 45 |         await element.updateComplete;
 46 | 
 47 |         controller.value = undefined;
 48 |         await element.updateComplete;
 49 | 
 50 |         const storageValue = window.localStorage.getItem('test-key');
 51 | 
 52 |         assert.equal(controller.value, undefined);
 53 |         assert.equal(element.shadowRoot!.textContent, '');
 54 |         assert.is(storageValue, null);
 55 |       });
 56 | 
 57 |       test('updates other instances', async () => {
 58 |         const otherController = new LocalStorageController(element, 'test-key');
 59 |         element.controllers.push(otherController);
 60 | 
 61 |         otherController.value = [1, 2];
 62 |         await element.updateComplete;
 63 | 
 64 |         const storageValue = window.localStorage.getItem('test-key');
 65 | 
 66 |         assert.equal(otherController.value, [1, 2]);
 67 |         assert.equal(element.shadowRoot!.textContent, '[1,2]');
 68 |         assert.is(storageValue, '[1,2]');
 69 |       });
 70 |     });
 71 | 
 72 |     test('reacts to storage events', async () => {
 73 |       window.localStorage.setItem('test-key', '[3,4]');
 74 |       window.dispatchEvent(
 75 |         new StorageEvent('storage', {
 76 |           storageArea: window.localStorage,
 77 |           key: 'test-key'
 78 |         })
 79 |       );
 80 | 
 81 |       await element.updateComplete;
 82 | 
 83 |       assert.equal(controller.value, [3, 4]);
 84 |       assert.equal(element.shadowRoot!.textContent, '[3,4]');
 85 |     });
 86 |   });
 87 | 
 88 |   suite('with default value', () => {
 89 |     setup(async () => {
 90 |       element = document.createElement('test-element') as TestElement;
 91 |       controller = new LocalStorageController(element, 'test-key', [5, 6]);
 92 |       element.controllers.push(controller);
 93 |       element.template = () => html`${JSON.stringify(controller.value)}`;
 94 |       document.body.appendChild(element);
 95 |       await element.updateComplete;
 96 |     });
 97 | 
 98 |     test('initialises to default value', () => {
 99 |       const storageValue = window.localStorage.getItem('test-key');
100 | 
101 |       assert.equal(controller.value, [5, 6]);
102 |       assert.equal(element.shadowRoot!.textContent, '[5,6]');
103 |       assert.is(storageValue, '[5,6]');
104 |     });
105 |   });
106 | 
107 |   suite('with saved value', () => {
108 |     setup(() => {
109 |       window.localStorage.setItem('test-key', JSON.stringify([7, 8]));
110 |       element = document.createElement('test-element') as TestElement;
111 |       element.template = () => html`${JSON.stringify(controller.value)}`;
112 |       document.body.appendChild(element);
113 |     });
114 | 
115 |     test('initialises to saved value', async () => {
116 |       controller = new LocalStorageController(element, 'test-key');
117 |       element.controllers.push(controller);
118 |       await element.updateComplete;
119 | 
120 |       const storageValue = window.localStorage.getItem('test-key');
121 |       assert.equal(controller.value, [7, 8]);
122 |       assert.equal(element.shadowRoot!.textContent, '[7,8]');
123 |       assert.is(storageValue, '[7,8]');
124 |     });
125 | 
126 |     test('ignore default value and use saved value', async () => {
127 |       controller = new LocalStorageController(element, 'test-key', [9, 10]);
128 |       element.controllers.push(controller);
129 |       await element.updateComplete;
130 | 
131 |       const storageValue = window.localStorage.getItem('test-key');
132 |       assert.equal(controller.value, [7, 8]);
133 |       assert.equal(element.shadowRoot!.textContent, '[7,8]');
134 |       assert.is(storageValue, '[7,8]');
135 |     });
136 |   });
137 | });
138 | 


--------------------------------------------------------------------------------
/src/test/controllers/markdown_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import {html} from 'lit';
  4 | import * as hanbi from 'hanbi';
  5 | import type {PropertyDeclarations} from 'lit';
  6 | import * as assert from 'uvu/assert';
  7 | import {MarkdownController, MarkdownOptions} from '../../main.js';
  8 | import {TestElementBase} from '../util.js';
  9 | 
 10 | /**
 11 |  * Test element for the markdown controller
 12 |  */
 13 | class MarkdownTestElement extends TestElementBase {
 14 |   public prop?: string;
 15 | 
 16 |   /** @inheritdoc */
 17 |   public static override get properties(): PropertyDeclarations {
 18 |     return {
 19 |       prop: {type: String}
 20 |     };
 21 |   }
 22 | }
 23 | 
 24 | customElements.define('markdown-test', MarkdownTestElement);
 25 | 
 26 | suite('MarkdownController', () => {
 27 |   let element: MarkdownTestElement;
 28 |   let controller: MarkdownController<MarkdownTestElement, 'prop'>;
 29 | 
 30 |   teardown(() => {
 31 |     element.remove();
 32 |     hanbi.restore();
 33 |   });
 34 | 
 35 |   suite('default', () => {
 36 |     setup(async () => {
 37 |       element = document.createElement('markdown-test') as MarkdownTestElement;
 38 |       controller = new MarkdownController(element);
 39 |       element.controllers.push(controller);
 40 |       element.template = () => html`${controller.value}`;
 41 |       document.body.appendChild(element);
 42 |       await element.updateComplete;
 43 |     });
 44 | 
 45 |     test('initialises to undefined', () => {
 46 |       assert.equal(controller.value, undefined);
 47 |       assert.equal(element.shadowRoot!.textContent, '');
 48 |     });
 49 | 
 50 |     suite('setValue', () => {
 51 |       test('updates markdown with new value', async () => {
 52 |         await controller.setValue('foo');
 53 |         await element.updateComplete;
 54 | 
 55 |         assert.is.not(controller.value, undefined);
 56 |         assert.match(element.shadowRoot!.innerHTML, '<p>foo</p>');
 57 |       });
 58 | 
 59 |       test('leaves markdown untouched if last value unchanged', async () => {
 60 |         await controller.setValue('foo');
 61 |         await element.updateComplete;
 62 | 
 63 |         const p = element.shadowRoot!.querySelector('p')!;
 64 | 
 65 |         await controller.setValue('foo');
 66 |         await element.updateComplete;
 67 | 
 68 |         const newP = element.shadowRoot!.querySelector('p')!;
 69 | 
 70 |         assert.is(newP, p);
 71 |         assert.is.not(controller.value, undefined);
 72 |         assert.match(element.shadowRoot!.innerHTML, '<p>foo</p>');
 73 |       });
 74 |     });
 75 | 
 76 |     suite('options', () => {
 77 |       setup(async () => {
 78 |         await controller.setValue('# foo');
 79 |         await element.updateComplete;
 80 |       });
 81 | 
 82 |       test('recomputes value if options changed', async () => {
 83 |         assert.match(element.shadowRoot!.innerHTML, '<h1 id="foo">foo</h1>');
 84 | 
 85 |         controller.options = {
 86 |           markedOptions: {
 87 |             headerIds: false
 88 |           }
 89 |         };
 90 | 
 91 |         await element.updateComplete;
 92 | 
 93 |         assert.match(element.shadowRoot!.innerHTML, '<h1>foo</h1>');
 94 |       });
 95 | 
 96 |       test('does not recompute if options same', async () => {
 97 |         const spy = hanbi.spy();
 98 |         const opts: MarkdownOptions<'prop'> = {
 99 |           markedOptions: {
100 |             walkTokens: spy.handler
101 |           }
102 |         };
103 | 
104 |         controller.options = opts;
105 |         await element.updateComplete;
106 | 
107 |         assert.is(spy.callCount, 2);
108 | 
109 |         controller.options = opts;
110 |         await element.updateComplete;
111 | 
112 |         assert.is(spy.callCount, 2);
113 |       });
114 |     });
115 |   });
116 | 
117 |   suite('options.property', () => {
118 |     setup(async () => {
119 |       element = document.createElement('markdown-test') as MarkdownTestElement;
120 |       element.prop = 'foo';
121 |       controller = new MarkdownController(element, {property: 'prop'});
122 |       element.controllers.push(controller);
123 |       element.template = () => html`${controller.value}`;
124 |       document.body.appendChild(element);
125 |       await element.updateComplete;
126 |     });
127 | 
128 |     test('initialises to current property value', () => {
129 |       assert.is.not(controller.value, undefined);
130 |       assert.match(element.shadowRoot!.innerHTML, '<p>foo</p>');
131 |     });
132 | 
133 |     test('observes changes to property', async () => {
134 |       element.prop = 'bar';
135 |       await element.updateComplete;
136 | 
137 |       assert.is.not(controller.value, undefined);
138 |       assert.match(element.shadowRoot!.innerHTML, '<p>bar</p>');
139 |     });
140 |   });
141 | });
142 | 


--------------------------------------------------------------------------------
/src/test/controllers/permissions_test.ts:
--------------------------------------------------------------------------------
 1 | import '../util.js';
 2 | 
 3 | import {html, ReactiveController} from 'lit';
 4 | import * as assert from 'uvu/assert';
 5 | import * as hanbi from 'hanbi';
 6 | import {PermissionsController} from '../../main.js';
 7 | import type {TestElement} from '../util.js';
 8 | 
 9 | suite('PermissionsController', () => {
10 |   let element: TestElement;
11 |   let controller: PermissionsController;
12 |   let permissionStub: hanbi.Stub<typeof navigator.permissions.query>;
13 |   let eventSpy: hanbi.Stub<(name: string, handler: unknown) => void>;
14 |   let mockStatus: PermissionStatus;
15 |   let mockState: PermissionState;
16 |   let permissionResolver: (state: PermissionStatus) => void;
17 | 
18 |   setup(async () => {
19 |     eventSpy = hanbi.spy();
20 |     mockState = 'prompt';
21 |     mockStatus = {
22 |       name: 'geolocation',
23 |       addEventListener: eventSpy.handler,
24 |       get state() {
25 |         return mockState;
26 |       }
27 |     } as PermissionStatus;
28 |     permissionStub = hanbi.stubMethod(navigator.permissions, 'query');
29 |     permissionStub.callsFake(() => {
30 |       return new Promise<PermissionStatus>((res) => {
31 |         permissionResolver = res;
32 |       });
33 |     });
34 |     element = document.createElement('test-element') as TestElement;
35 |     controller = new PermissionsController(element, 'geolocation');
36 |     element.controllers.push(controller as ReactiveController);
37 |     element.template = () => html`${controller.state}`;
38 |     document.body.appendChild(element);
39 |     await element.updateComplete;
40 |   });
41 | 
42 |   teardown(() => {
43 |     element.remove();
44 |     hanbi.restore();
45 |   });
46 | 
47 |   test('initialises to pending', () => {
48 |     assert.equal(controller.state, 'pending');
49 |     assert.equal(element.shadowRoot!.textContent, 'pending');
50 |   });
51 | 
52 |   test('changes from pending to prompt', async () => {
53 |     permissionResolver(mockStatus);
54 |     // TODO (43081j): be sure why two renders happen here
55 |     await element.updateComplete;
56 |     await element.updateComplete;
57 |     assert.equal(controller.state, 'prompt');
58 |     assert.equal(element.shadowRoot!.textContent, 'prompt');
59 |   });
60 | 
61 |   test('observes permission changes', async () => {
62 |     permissionResolver(mockStatus);
63 |     await element.updateComplete;
64 | 
65 |     const changeHandler = [...eventSpy.calls].find(
66 |       (c) => c.args[0] === 'change'
67 |     )!.args[1];
68 | 
69 |     mockState = 'granted';
70 |     (changeHandler as () => void)();
71 | 
72 |     await element.updateComplete;
73 |     assert.equal(controller.state, 'granted');
74 |     assert.equal(element.shadowRoot!.textContent, 'granted');
75 |   });
76 | });
77 | 


--------------------------------------------------------------------------------
/src/test/controllers/propertyHistory_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import {html, PropertyDeclarations} from 'lit';
  4 | import * as assert from 'uvu/assert';
  5 | import {PropertyHistoryController} from '../../main.js';
  6 | import {TestElementBase} from '../util.js';
  7 | 
  8 | /**
  9 |  * Test element for the property history controller
 10 |  */
 11 | class PropertyHistoryTestElement extends TestElementBase {
 12 |   public prop?: string;
 13 | 
 14 |   /** @inheritdoc */
 15 |   public static override get properties(): PropertyDeclarations {
 16 |     return {
 17 |       prop: {type: String}
 18 |     };
 19 |   }
 20 | }
 21 | 
 22 | customElements.define('property-history-test', PropertyHistoryTestElement);
 23 | 
 24 | suite('PropertyHistoryController', () => {
 25 |   let element: PropertyHistoryTestElement;
 26 |   let controller: PropertyHistoryController<PropertyHistoryTestElement, 'prop'>;
 27 | 
 28 |   setup(async () => {
 29 |     element = document.createElement(
 30 |       'property-history-test'
 31 |     ) as PropertyHistoryTestElement;
 32 |     controller = new PropertyHistoryController(element, 'prop');
 33 |     element.controllers.push(controller);
 34 |     element.template = () => html`Last: ${controller.lastChanged}`;
 35 |     document.body.appendChild(element);
 36 |     await element.updateComplete;
 37 |   });
 38 | 
 39 |   teardown(() => {
 40 |     element.remove();
 41 |   });
 42 | 
 43 |   test('initialises with current value', () => {
 44 |     assert.is.not(controller.lastChanged, undefined);
 45 |     assert.is.not(element.shadowRoot!.textContent, 'Last: ');
 46 |   });
 47 | 
 48 |   test('observes changes to property', async () => {
 49 |     const prevValue = controller.lastChanged;
 50 | 
 51 |     element.prop = 'foo';
 52 |     await element.updateComplete;
 53 | 
 54 |     assert.is.not(controller.lastChanged, prevValue);
 55 |     assert.not.equal(element.shadowRoot!.textContent, 'Last: ');
 56 |   });
 57 | 
 58 |   test('no value change if property value same', async () => {
 59 |     element.prop = 'foo';
 60 |     await element.updateComplete;
 61 | 
 62 |     const prevValue = controller.lastChanged;
 63 | 
 64 |     element.prop = 'foo';
 65 |     await element.updateComplete;
 66 | 
 67 |     assert.is(controller.lastChanged, prevValue);
 68 |   });
 69 | 
 70 |   suite('undo', () => {
 71 |     test('can undo to previous value', async () => {
 72 |       element.prop = 'foo';
 73 |       await element.updateComplete;
 74 | 
 75 |       const prevValue = controller.lastChanged;
 76 | 
 77 |       controller.undo();
 78 |       await element.updateComplete;
 79 | 
 80 |       assert.equal(element.prop, undefined);
 81 |       assert.is.not(prevValue, controller.lastChanged);
 82 |     });
 83 | 
 84 |     test('can undo multiple times', async () => {
 85 |       element.prop = 'foo';
 86 |       await element.updateComplete;
 87 |       element.prop = 'bar';
 88 |       await element.updateComplete;
 89 |       element.prop = 'baz';
 90 |       await element.updateComplete;
 91 | 
 92 |       controller.undo();
 93 |       await element.updateComplete;
 94 |       controller.undo();
 95 |       await element.updateComplete;
 96 | 
 97 |       assert.equal(element.prop, 'foo');
 98 |     });
 99 | 
100 |     test('cannot undo beyond start value', async () => {
101 |       controller.undo();
102 |       await element.updateComplete;
103 | 
104 |       assert.equal(element.prop, undefined);
105 |     });
106 |   });
107 | 
108 |   suite('redo', () => {
109 |     test('can redo to an undone value', async () => {
110 |       element.prop = 'foo';
111 |       await element.updateComplete;
112 | 
113 |       controller.undo();
114 |       await element.updateComplete;
115 | 
116 |       const prevValue = controller.lastChanged;
117 | 
118 |       controller.redo();
119 |       await element.updateComplete;
120 | 
121 |       assert.equal(element.prop, 'foo');
122 |       assert.is.not(prevValue, controller.lastChanged);
123 |     });
124 | 
125 |     test('can redo multiple times', async () => {
126 |       element.prop = 'foo';
127 |       await element.updateComplete;
128 |       element.prop = 'bar';
129 |       await element.updateComplete;
130 |       element.prop = 'baz';
131 |       await element.updateComplete;
132 | 
133 |       controller.undo(); // bar
134 |       controller.undo(); // foo
135 |       controller.redo(); // bar
136 |       controller.redo(); // baz
137 | 
138 |       await element.updateComplete;
139 | 
140 |       assert.equal(element.prop, 'baz');
141 |     });
142 | 
143 |     test('cannot redo beyond latest value', async () => {
144 |       controller.redo();
145 |       await element.updateComplete;
146 | 
147 |       assert.equal(element.prop, undefined);
148 |     });
149 |   });
150 | });
151 | 


--------------------------------------------------------------------------------
/src/test/controllers/sessionStorage_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import {html} from 'lit';
  4 | import * as assert from 'uvu/assert';
  5 | import {SessionStorageController} from '../../main.js';
  6 | import type {TestElement} from '../util.js';
  7 | 
  8 | suite('SessionStorageController', () => {
  9 |   let element: TestElement;
 10 |   let controller: SessionStorageController<[number, number]>;
 11 | 
 12 |   teardown(() => {
 13 |     element.remove();
 14 |     window.sessionStorage.removeItem('test-key');
 15 |   });
 16 | 
 17 |   suite('default', () => {
 18 |     setup(async () => {
 19 |       element = document.createElement('test-element') as TestElement;
 20 |       controller = new SessionStorageController(element, 'test-key');
 21 |       element.controllers.push(controller);
 22 |       element.template = () => html`${JSON.stringify(controller.value)}`;
 23 |       document.body.appendChild(element);
 24 |     });
 25 | 
 26 |     test('initialises to undefined', () => {
 27 |       assert.equal(controller.value, undefined);
 28 |       assert.equal(element.shadowRoot!.textContent, '');
 29 |     });
 30 | 
 31 |     suite('set value', () => {
 32 |       test('sets value in session storage', async () => {
 33 |         controller.value = [0, 0];
 34 |         await element.updateComplete;
 35 | 
 36 |         const storageValue = window.sessionStorage.getItem('test-key');
 37 | 
 38 |         assert.equal(controller.value, [0, 0]);
 39 |         assert.equal(element.shadowRoot!.textContent, '[0,0]');
 40 |         assert.is(storageValue, '[0,0]');
 41 |       });
 42 | 
 43 |       test('removes from storage if value undefined', async () => {
 44 |         controller.value = [0, 0];
 45 |         await element.updateComplete;
 46 | 
 47 |         controller.value = undefined;
 48 |         await element.updateComplete;
 49 | 
 50 |         const storageValue = window.sessionStorage.getItem('test-key');
 51 | 
 52 |         assert.equal(controller.value, undefined);
 53 |         assert.equal(element.shadowRoot!.textContent, '');
 54 |         assert.is(storageValue, null);
 55 |       });
 56 | 
 57 |       test('updates other instances', async () => {
 58 |         const otherController = new SessionStorageController(
 59 |           element,
 60 |           'test-key'
 61 |         );
 62 |         element.controllers.push(otherController);
 63 | 
 64 |         otherController.value = [1, 2];
 65 |         await element.updateComplete;
 66 | 
 67 |         const storageValue = window.sessionStorage.getItem('test-key');
 68 | 
 69 |         assert.equal(otherController.value, [1, 2]);
 70 |         assert.equal(element.shadowRoot!.textContent, '[1,2]');
 71 |         assert.is(storageValue, '[1,2]');
 72 |       });
 73 |     });
 74 | 
 75 |     test('reacts to storage events', async () => {
 76 |       window.sessionStorage.setItem('test-key', '[3,4]');
 77 |       window.dispatchEvent(
 78 |         new StorageEvent('storage', {
 79 |           storageArea: window.sessionStorage,
 80 |           key: 'test-key'
 81 |         })
 82 |       );
 83 | 
 84 |       await element.updateComplete;
 85 | 
 86 |       assert.equal(controller.value, [3, 4]);
 87 |       assert.equal(element.shadowRoot!.textContent, '[3,4]');
 88 |     });
 89 |   });
 90 | 
 91 |   suite('with default value', () => {
 92 |     setup(async () => {
 93 |       element = document.createElement('test-element') as TestElement;
 94 |       controller = new SessionStorageController(element, 'test-key', [5, 6]);
 95 |       element.controllers.push(controller);
 96 |       element.template = () => html`${JSON.stringify(controller.value)}`;
 97 |       document.body.appendChild(element);
 98 |       await element.updateComplete;
 99 |     });
100 | 
101 |     test('initialises to default value', () => {
102 |       const storageValue = window.sessionStorage.getItem('test-key');
103 | 
104 |       assert.equal(controller.value, [5, 6]);
105 |       assert.equal(element.shadowRoot!.textContent, '[5,6]');
106 |       assert.is(storageValue, '[5,6]');
107 |     });
108 |   });
109 | 
110 |   suite('with saved value', () => {
111 |     setup(() => {
112 |       window.sessionStorage.setItem('test-key', JSON.stringify([7, 8]));
113 |       element = document.createElement('test-element') as TestElement;
114 |       element.template = () => html`${JSON.stringify(controller.value)}`;
115 |       document.body.appendChild(element);
116 |     });
117 | 
118 |     test('initialises to saved value', async () => {
119 |       controller = new SessionStorageController(element, 'test-key');
120 |       element.controllers.push(controller);
121 |       await element.updateComplete;
122 | 
123 |       const storageValue = window.sessionStorage.getItem('test-key');
124 |       assert.equal(controller.value, [7, 8]);
125 |       assert.equal(element.shadowRoot!.textContent, '[7,8]');
126 |       assert.is(storageValue, '[7,8]');
127 |     });
128 | 
129 |     test('ignore default value and use saved value', async () => {
130 |       controller = new SessionStorageController(element, 'test-key', [9, 10]);
131 |       element.controllers.push(controller);
132 |       await element.updateComplete;
133 | 
134 |       const storageValue = window.sessionStorage.getItem('test-key');
135 |       assert.equal(controller.value, [7, 8]);
136 |       assert.equal(element.shadowRoot!.textContent, '[7,8]');
137 |       assert.is(storageValue, '[7,8]');
138 |     });
139 |   });
140 | });
141 | 


--------------------------------------------------------------------------------
/src/test/controllers/slot_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import {html} from 'lit';
  4 | import * as hanbi from 'hanbi';
  5 | import * as assert from 'uvu/assert';
  6 | import {SlotController} from '../../main.js';
  7 | import type {TestElement} from '../util.js';
  8 | import {ref, createRef} from 'lit/directives/ref.js';
  9 | 
 10 | suite('SlotController', () => {
 11 |   let element: TestElement;
 12 |   let controller: SlotController;
 13 | 
 14 |   setup(() => {
 15 |     element = document.createElement('test-element');
 16 |   });
 17 | 
 18 |   teardown(() => {
 19 |     element.remove();
 20 |   });
 21 | 
 22 |   setup(async () => {
 23 |     controller = new SlotController(element);
 24 |     element.controllers.push(controller);
 25 |     element.template = () => html`<slot></slot>`;
 26 |     document.body.appendChild(element);
 27 |     await element.updateComplete;
 28 |   });
 29 | 
 30 |   suite('addListener', () => {
 31 |     test('calls listener with slotted elements', async () => {
 32 |       const spy = hanbi.spy<(node: Element) => void>();
 33 | 
 34 |       controller.addListener('*', '*', spy.handler);
 35 | 
 36 |       element.innerHTML = '<span>foo</span><div>bar</div>';
 37 |       await element.updateComplete;
 38 | 
 39 |       const spanNode = element.querySelector('span')!;
 40 |       const divNode = element.querySelector('div')!;
 41 | 
 42 |       assert.is(spy.callCount, 2);
 43 | 
 44 |       const firstCall = spy.getCall(0);
 45 |       const secondCall = spy.getCall(1);
 46 | 
 47 |       assert.is(firstCall.args[0], spanNode);
 48 |       assert.is(secondCall.args[0], divNode);
 49 |     });
 50 | 
 51 |     test('does not call listener for other slot', async () => {
 52 |       const spy = hanbi.spy<(node: Element) => void>();
 53 | 
 54 |       element.template = () => html`
 55 |         <slot name="test"></slot>
 56 |         <slot name="test2"></slot>
 57 |       `;
 58 |       await element.updateComplete;
 59 | 
 60 |       controller.addListener('test', '*', spy.handler);
 61 | 
 62 |       element.innerHTML = `
 63 |         <span slot="test2">foo</span>
 64 |       `;
 65 |       await element.updateComplete;
 66 | 
 67 |       assert.is(spy.callCount, 0);
 68 |     });
 69 | 
 70 |     test('simple selector matches elements', async () => {
 71 |       const spy = hanbi.spy<(node: HTMLSpanElement) => void>();
 72 | 
 73 |       controller.addListener('*', 'span', spy.handler);
 74 | 
 75 |       element.innerHTML = '<span>foo</span><div>bar</div>';
 76 |       await element.updateComplete;
 77 | 
 78 |       const spanNode = element.querySelector('span')!;
 79 | 
 80 |       assert.is(spy.callCount, 1);
 81 | 
 82 |       const firstCall = spy.getCall(0);
 83 | 
 84 |       assert.is(firstCall.args[0], spanNode);
 85 |     });
 86 | 
 87 |     test('complex selector matches elements', async () => {
 88 |       const spy = hanbi.spy<(node: Element) => void>();
 89 | 
 90 |       controller.addListener('*', 'span,div', spy.handler);
 91 | 
 92 |       element.innerHTML = '<span>foo</span><div>bar</div><h1>baz</h1>';
 93 |       await element.updateComplete;
 94 | 
 95 |       const spanNode = element.querySelector('span')!;
 96 |       const divNode = element.querySelector('div')!;
 97 | 
 98 |       assert.is(spy.callCount, 2);
 99 | 
100 |       const firstCall = spy.getCall(0);
101 |       const secondCall = spy.getCall(1);
102 | 
103 |       assert.is(firstCall.args[0], spanNode);
104 |       assert.is(secondCall.args[0], divNode);
105 |     });
106 | 
107 |     test('observes element changes', async () => {
108 |       const spy = hanbi.spy<(node: Element) => void>();
109 | 
110 |       controller.addListener('*', '*', spy.handler);
111 | 
112 |       element.template = () => html`<div><slot></slot></div>`;
113 |       await element.updateComplete;
114 | 
115 |       element.innerHTML = '<span>foo</span><div>bar</div>';
116 |       await element.updateComplete;
117 | 
118 |       assert.is(spy.callCount, 2);
119 |     });
120 | 
121 |     test('can specify exact slot by name', async () => {
122 |       const spy = hanbi.spy<(node: Element) => void>();
123 | 
124 |       element.template = () => html`<slot name="test"></slot>`;
125 |       await element.updateComplete;
126 | 
127 |       controller.addListener('test', '*', spy.handler);
128 | 
129 |       element.innerHTML = '<span slot="test">foo</span><div>bar</div>';
130 |       await element.updateComplete;
131 | 
132 |       const spanNode = element.querySelector('span')!;
133 | 
134 |       assert.is(spy.callCount, 1);
135 | 
136 |       const firstCall = spy.getCall(0);
137 | 
138 |       assert.is(firstCall.args[0], spanNode);
139 |     });
140 | 
141 |     test('can specify exact slot by ref', async () => {
142 |       const spy = hanbi.spy<(node: Element) => void>();
143 |       const slotRef = createRef<HTMLSlotElement>();
144 | 
145 |       element.template = () => html`
146 |         <slot name="test" ${ref(slotRef)}></slot>
147 |       `;
148 |       await element.updateComplete;
149 | 
150 |       controller.addListener(slotRef, '*', spy.handler);
151 | 
152 |       element.innerHTML = '<span slot="test">foo</span><div>bar</div>';
153 |       await element.updateComplete;
154 | 
155 |       const spanNode = element.querySelector('span')!;
156 | 
157 |       assert.is(spy.callCount, 1);
158 | 
159 |       const firstCall = spy.getCall(0);
160 | 
161 |       assert.is(firstCall.args[0], spanNode);
162 |     });
163 | 
164 |     test('can specify default slot', async () => {
165 |       const spy = hanbi.spy<(node: Element) => void>();
166 | 
167 |       controller.addListener('[default]', '*', spy.handler);
168 | 
169 |       element.innerHTML = '<span>foo</span><div>bar</div>';
170 |       await element.updateComplete;
171 | 
172 |       const spanNode = element.querySelector('span')!;
173 |       const divNode = element.querySelector('div')!;
174 | 
175 |       assert.is(spy.callCount, 2);
176 | 
177 |       const firstCall = spy.getCall(0);
178 |       const secondCall = spy.getCall(1);
179 | 
180 |       assert.is(firstCall.args[0], spanNode);
181 |       assert.is(secondCall.args[0], divNode);
182 |     });
183 |   });
184 | 
185 |   suite('has', () => {
186 |     test('false if no slot name', async () => {
187 |       assert.is(controller.has(''), false);
188 |     });
189 | 
190 |     test('true if slot has elements', async () => {
191 |       element.template = () => html`
192 |         <slot name="test"></slot>
193 |       `;
194 |       await element.updateComplete;
195 | 
196 |       assert.is(controller.has('test'), false);
197 | 
198 |       element.innerHTML = `
199 |         <span slot="test">foo</span>
200 |       `;
201 | 
202 |       assert.is(controller.has('test'), true);
203 |     });
204 | 
205 |     test('can pass slot as ref', async () => {
206 |       const slotRef = createRef<HTMLSlotElement>();
207 | 
208 |       element.template = () => html`
209 |         <slot name="test" ${ref(slotRef)}></slot>
210 |       `;
211 |       await element.updateComplete;
212 | 
213 |       assert.is(controller.has(slotRef), false);
214 | 
215 |       element.innerHTML = `
216 |         <span slot="test">foo</span>
217 |       `;
218 | 
219 |       assert.is(controller.has(slotRef), true);
220 |     });
221 | 
222 |     test('true if any slot has elements (slot=*)', async () => {
223 |       element.template = () => html`
224 |         <slot name="test"></slot>
225 |         <slot></slot>
226 |       `;
227 |       await element.updateComplete;
228 | 
229 |       assert.is(controller.has('*'), false);
230 | 
231 |       element.innerHTML = `
232 |         <span slot="test">foo</span>
233 |         <span>bar</span>
234 |       `;
235 | 
236 |       assert.is(controller.has('*'), true);
237 |     });
238 | 
239 |     test('true if any slot has matching elements (slot=*)', async () => {
240 |       element.template = () => html`
241 |         <slot name="test"></slot>
242 |         <slot></slot>
243 |       `;
244 |       await element.updateComplete;
245 | 
246 |       assert.is(controller.has('*', 'span'), false);
247 | 
248 |       element.innerHTML = `
249 |         <div slot="test">foo</div>
250 |         <span>bar</span>
251 |       `;
252 | 
253 |       assert.is(controller.has('*', 'span'), true);
254 |     });
255 | 
256 |     test('true if slot has matching elements', async () => {
257 |       element.template = () => html`<slot name="test"></slot>`;
258 |       await element.updateComplete;
259 | 
260 |       element.innerHTML = '<span slot="test">foo</span>';
261 | 
262 |       assert.is(controller.has('test', 'span'), true);
263 |       assert.is(controller.has('test', 'div'), false);
264 |     });
265 | 
266 |     test('true if default slot has elements', () => {
267 |       assert.is(controller.has('[default]'), false);
268 | 
269 |       element.innerHTML = '<span>foo</span>';
270 | 
271 |       assert.is(controller.has('[default]'), true);
272 |     });
273 | 
274 |     test('false if not the specified slot', async () => {
275 |       element.template = () => html`
276 |         <slot name="test"></slot>
277 |         <slot name="test2"></slot>
278 |       `;
279 |       await element.updateComplete;
280 | 
281 |       assert.is(controller.has('test'), false);
282 | 
283 |       element.innerHTML = `
284 |         <div slot="test2">foo</div>
285 |       `;
286 | 
287 |       assert.is(controller.has('test'), false);
288 |     });
289 | 
290 |     test('triggers re-render when condition changes', async () => {
291 |       element.template = () => html`
292 |         <slot></slot>
293 |         <span>${String(controller.has('*'))}</span>
294 |       `;
295 |       await element.updateComplete;
296 | 
297 |       const span = element.shadowRoot!.querySelector('span')!;
298 | 
299 |       assert.is(span.textContent, 'false');
300 | 
301 |       element.innerHTML = '<span>foo</span>';
302 |       await element.updateComplete;
303 |       await element.updateComplete;
304 | 
305 |       assert.is(span.textContent, 'true');
306 |     });
307 | 
308 |     test('handles re-renders with conditional has() calls', async () => {
309 |       let flag = true;
310 | 
311 |       element.template = () => html`
312 |         <slot></slot>
313 |         <span>${flag ? String(controller.has('*')) : 'nothing'}</span>
314 |       `;
315 |       await element.updateComplete;
316 | 
317 |       const span = element.shadowRoot!.querySelector('span')!;
318 | 
319 |       assert.is(span.textContent, 'false');
320 | 
321 |       flag = false;
322 |       element.requestUpdate();
323 |       await element.updateComplete;
324 | 
325 |       assert.is(span.textContent, 'nothing');
326 | 
327 |       flag = true;
328 |       element.requestUpdate();
329 |       await element.updateComplete;
330 | 
331 |       assert.is(span.textContent, 'false');
332 | 
333 |       element.innerHTML = '<span>foo</span>';
334 |       await element.updateComplete;
335 |       await element.updateComplete;
336 | 
337 |       assert.is(span.textContent, 'true');
338 |     });
339 |   });
340 | });
341 | 


--------------------------------------------------------------------------------
/src/test/controllers/windowScroll_test.ts:
--------------------------------------------------------------------------------
 1 | import '../util.js';
 2 | 
 3 | import {html} from 'lit';
 4 | import * as assert from 'uvu/assert';
 5 | import {WindowScrollController} from '../../main.js';
 6 | import type {TestElement} from '../util.js';
 7 | 
 8 | suite('WindowScrollController', () => {
 9 |   let element: TestElement;
10 |   let controller: WindowScrollController;
11 |   let tallDiv: HTMLElement;
12 | 
13 |   setup(async () => {
14 |     tallDiv = document.createElement('div');
15 |     tallDiv.style.height = '110vh';
16 |     tallDiv.style.width = '10rem';
17 |     element = document.createElement('test-element') as TestElement;
18 |     controller = new WindowScrollController(element);
19 |     element.controllers.push(controller);
20 |     element.template = () => html`x: ${controller.x}, y: ${controller.y}`;
21 |     document.body.appendChild(element);
22 |     document.body.appendChild(tallDiv);
23 |     await element.updateComplete;
24 |   });
25 | 
26 |   teardown(() => {
27 |     element.remove();
28 |     tallDiv.remove();
29 |   });
30 | 
31 |   test('initialises to current offset', () => {
32 |     assert.equal(controller.x, 0);
33 |     assert.equal(controller.y, 0);
34 |     assert.equal(element.shadowRoot!.textContent, 'x: 0, y: 0');
35 |   });
36 | 
37 |   test('observes changes in scroll offset', async () => {
38 |     window.scrollBy(0, 10);
39 | 
40 |     await new Promise((res) => {
41 |       window.requestAnimationFrame(res);
42 |     });
43 |     await element.updateComplete;
44 | 
45 |     assert.equal(controller.x, 0);
46 |     assert.equal(controller.y, 10);
47 |     assert.equal(element.shadowRoot!.textContent, 'x: 0, y: 10');
48 |   });
49 | });
50 | 


--------------------------------------------------------------------------------
/src/test/directives/bindInput_test.ts:
--------------------------------------------------------------------------------
  1 | import {html, PropertyDeclarations} from 'lit';
  2 | import * as assert from 'uvu/assert';
  3 | import {bindInput} from '../../main.js';
  4 | import {TestElementBase} from '../util.js';
  5 | 
  6 | /**
  7 |  * Test element for the input directive
  8 |  */
  9 | class BindInputDirectiveTest extends TestElementBase {
 10 |   public prop?: unknown;
 11 | 
 12 |   /** @inheritdoc */
 13 |   public static override get properties(): PropertyDeclarations {
 14 |     return {
 15 |       prop: {type: Object}
 16 |     };
 17 |   }
 18 | }
 19 | 
 20 | customElements.define('bind-input-directive-test', BindInputDirectiveTest);
 21 | 
 22 | suite('bindInput directive', () => {
 23 |   let element: BindInputDirectiveTest;
 24 | 
 25 |   setup(async () => {
 26 |     element = document.createElement(
 27 |       'bind-input-directive-test'
 28 |     ) as BindInputDirectiveTest;
 29 |     document.body.appendChild(element);
 30 |   });
 31 | 
 32 |   teardown(() => {
 33 |     element.remove();
 34 |   });
 35 | 
 36 |   test('throws on non-element binding', async () => {
 37 |     try {
 38 |       element.template = () => html`
 39 |         <div>${bindInput(element, 'prop')}</div>
 40 |       `;
 41 |       await element.updateComplete;
 42 |       assert.unreachable();
 43 |     } catch (err) {
 44 |       assert.is(
 45 |         (err as Error).message,
 46 |         'The `bindInput` directive must be used in an element or ' +
 47 |           'attribute binding'
 48 |       );
 49 |     }
 50 |   });
 51 | 
 52 |   test('does nothing for non-existent properties', async () => {
 53 |     element.template = () => html`
 54 |       <input ${bindInput(element, 'nonsense' as keyof BindInputDirectiveTest)}>
 55 |     `;
 56 |     await element.updateComplete;
 57 | 
 58 |     const node = element.shadowRoot!.querySelector('input')!;
 59 | 
 60 |     assert.is(node.value, '');
 61 |     assert.is(element.prop, undefined);
 62 |   });
 63 | 
 64 |   test('does nothing for non-existent properties (upwards)', async () => {
 65 |     element.template = () => html`
 66 |       <input ${bindInput(element, 'nonsense' as keyof BindInputDirectiveTest)}>
 67 |     `;
 68 |     await element.updateComplete;
 69 | 
 70 |     const node = element.shadowRoot!.querySelector('input')!;
 71 | 
 72 |     node.value = 'foo';
 73 |     node.dispatchEvent(new Event('input'));
 74 |     await element.updateComplete;
 75 | 
 76 |     assert.is(element.prop, undefined);
 77 |     assert.is(Object.prototype.hasOwnProperty.call(element, 'nonsense'), false);
 78 |   });
 79 | 
 80 |   test('survives DOM reconnect', async () => {
 81 |     element.template = () => html`
 82 |       <input ${bindInput(element, 'prop')}>
 83 |     `;
 84 |     await element.updateComplete;
 85 | 
 86 |     const inputNode = element.shadowRoot!.querySelector('input')!;
 87 |     element.remove();
 88 | 
 89 |     inputNode.value = 'xyz';
 90 |     inputNode.dispatchEvent(new Event('input'));
 91 | 
 92 |     assert.is(element.prop, undefined);
 93 | 
 94 |     document.body.appendChild(element);
 95 | 
 96 |     inputNode.value = 'xyz';
 97 |     inputNode.dispatchEvent(new Event('input'));
 98 | 
 99 |     assert.is(element.prop, 'xyz');
100 |   });
101 | 
102 |   suite('<input> by property', () => {
103 |     setup(async () => {
104 |       element.template = () => html`
105 |         <input .value=${bindInput(element, 'prop')}>
106 |       `;
107 |       await element.updateComplete;
108 |     });
109 | 
110 |     test('propagates value downwards', async () => {
111 |       element.prop = 'xyz';
112 |       await element.updateComplete;
113 | 
114 |       const inputNode = element.shadowRoot!.querySelector('input')!;
115 | 
116 |       assert.is(inputNode.value, 'xyz');
117 |     });
118 | 
119 |     test('propagates value upwards', async () => {
120 |       const inputNode = element.shadowRoot!.querySelector('input')!;
121 | 
122 |       inputNode.value = 'xyz';
123 |       inputNode.dispatchEvent(new Event('input'));
124 |       await element.updateComplete;
125 | 
126 |       assert.is(element.prop, 'xyz');
127 |     });
128 |   });
129 | 
130 |   suite('<input> by attribute', () => {
131 |     setup(async () => {
132 |       element.template = () => html`
133 |         <input value=${bindInput(element, 'prop')}>
134 |       `;
135 |       await element.updateComplete;
136 |     });
137 | 
138 |     test('propagates value downwards', async () => {
139 |       element.prop = 'xyz';
140 |       await element.updateComplete;
141 | 
142 |       const inputNode = element.shadowRoot!.querySelector('input')!;
143 | 
144 |       assert.is(inputNode.value, 'xyz');
145 |     });
146 | 
147 |     test('propagates value upwards', async () => {
148 |       const inputNode = element.shadowRoot!.querySelector('input')!;
149 | 
150 |       inputNode.value = 'xyz';
151 |       inputNode.dispatchEvent(new Event('input'));
152 |       await element.updateComplete;
153 | 
154 |       assert.is(element.prop, 'xyz');
155 |     });
156 |   });
157 | 
158 |   suite('<input>', () => {
159 |     setup(async () => {
160 |       element.template = () => html`
161 |         <input ${bindInput(element, 'prop')}>
162 |       `;
163 |       await element.updateComplete;
164 |     });
165 | 
166 |     test('propagates value downwards', async () => {
167 |       element.prop = 'xyz';
168 |       await element.updateComplete;
169 | 
170 |       const inputNode = element.shadowRoot!.querySelector('input')!;
171 | 
172 |       assert.is(inputNode.value, 'xyz');
173 |     });
174 | 
175 |     test('propagates value upwards', async () => {
176 |       const inputNode = element.shadowRoot!.querySelector('input')!;
177 | 
178 |       inputNode.value = 'xyz';
179 |       inputNode.dispatchEvent(new Event('input'));
180 |       await element.updateComplete;
181 | 
182 |       assert.is(element.prop, 'xyz');
183 |     });
184 | 
185 |     test('sets empty string on undefined value', async () => {
186 |       element.prop = 'xyz';
187 |       await element.updateComplete;
188 |       element.prop = undefined;
189 |       await element.updateComplete;
190 | 
191 |       const inputNode = element.shadowRoot!.querySelector('input')!;
192 | 
193 |       assert.is(inputNode.value, '');
194 |     });
195 |   });
196 | 
197 |   suite('<input type="checkbox">', () => {
198 |     setup(async () => {
199 |       element.template = () => html`
200 |         <input ${bindInput(element, 'prop')} type="checkbox">
201 |       `;
202 |       await element.updateComplete;
203 |     });
204 | 
205 |     test('propagates value downwards', async () => {
206 |       element.prop = true;
207 |       await element.updateComplete;
208 | 
209 |       const node = element.shadowRoot!.querySelector('input')!;
210 | 
211 |       assert.is(node.checked, true);
212 |     });
213 | 
214 |     test('propagates value upwards', async () => {
215 |       const node = element.shadowRoot!.querySelector('input')!;
216 | 
217 |       node.checked = true;
218 |       node.dispatchEvent(new Event('change'));
219 |       await element.updateComplete;
220 | 
221 |       assert.is(element.prop, true);
222 |     });
223 |   });
224 | 
225 |   suite('<select>', () => {
226 |     setup(async () => {
227 |       element.template = () => html`
228 |         <select ${bindInput(element, 'prop')}>
229 |           <option>xyz</option>
230 |         </select>
231 |       `;
232 |       await element.updateComplete;
233 |     });
234 | 
235 |     test('propagates value downwards', async () => {
236 |       element.prop = 'xyz';
237 |       await element.updateComplete;
238 | 
239 |       const node = element.shadowRoot!.querySelector('select')!;
240 | 
241 |       assert.is(node.value, 'xyz');
242 |     });
243 | 
244 |     test('propagates value upwards', async () => {
245 |       const node = element.shadowRoot!.querySelector('select')!;
246 | 
247 |       node.value = 'xyz';
248 |       node.dispatchEvent(new Event('change'));
249 |       await element.updateComplete;
250 | 
251 |       assert.is(element.prop, 'xyz');
252 |     });
253 |   });
254 | 
255 |   suite('<select multiple>', () => {
256 |     setup(async () => {
257 |       element.template = () => html`
258 |         <select ${bindInput(element, 'prop')} multiple>
259 |           <option>808</option>
260 |           <option>303</option>
261 |         </select>
262 |       `;
263 |       await element.updateComplete;
264 |     });
265 | 
266 |     test('propagates value downwards', async () => {
267 |       element.prop = ['808', '303'];
268 |       await element.updateComplete;
269 | 
270 |       const node = element.shadowRoot!.querySelector('select')!;
271 |       const opts = [...node.selectedOptions].map((opt) => opt.value);
272 | 
273 |       assert.is(opts.length, 2);
274 |       assert.equal(opts, ['808', '303']);
275 |     });
276 | 
277 |     test('propagates value upwards', async () => {
278 |       const node = element.shadowRoot!.querySelector('select')!;
279 |       const opts = [...node.options];
280 | 
281 |       opts[0]!.selected = true;
282 |       opts[1]!.selected = true;
283 |       node.dispatchEvent(new Event('change'));
284 |       await element.updateComplete;
285 | 
286 |       assert.equal(element.prop, ['808', '303']);
287 |     });
288 |   });
289 | 
290 |   suite('<textarea>', () => {
291 |     setup(async () => {
292 |       element.template = () => html`
293 |         <textarea ${bindInput(element, 'prop')}></textarea>
294 |       `;
295 |       await element.updateComplete;
296 |     });
297 | 
298 |     test('propagates value downwards', async () => {
299 |       element.prop = 'xyz';
300 |       await element.updateComplete;
301 | 
302 |       const node = element.shadowRoot!.querySelector('textarea')!;
303 | 
304 |       assert.is(node.value, 'xyz');
305 |     });
306 | 
307 |     test('propagates value upwards', async () => {
308 |       const node = element.shadowRoot!.querySelector('textarea')!;
309 | 
310 |       node.value = 'xyz';
311 |       node.dispatchEvent(new Event('input'));
312 |       await element.updateComplete;
313 | 
314 |       assert.is(element.prop, 'xyz');
315 |     });
316 | 
317 |     test('sets empty string on undefined value', async () => {
318 |       element.prop = 'xyz';
319 |       await element.updateComplete;
320 |       element.prop = undefined;
321 |       await element.updateComplete;
322 | 
323 |       const node = element.shadowRoot!.querySelector('textarea')!;
324 | 
325 |       assert.is(node.value, '');
326 |     });
327 |   });
328 | });
329 | 


--------------------------------------------------------------------------------
/src/test/directives/onLongPress_test.ts:
--------------------------------------------------------------------------------
  1 | import '../util.js';
  2 | 
  3 | import {html} from 'lit';
  4 | import * as assert from 'uvu/assert';
  5 | import {onLongPress} from '../../main.js';
  6 | import * as hanbi from 'hanbi';
  7 | import {TestElement, delay} from '../util.js';
  8 | 
  9 | suite('onLongPress directive', () => {
 10 |   let element: TestElement;
 11 | 
 12 |   setup(async () => {
 13 |     element = document.createElement('test-element');
 14 |     document.body.appendChild(element);
 15 |   });
 16 | 
 17 |   teardown(() => {
 18 |     element.remove();
 19 |     hanbi.restore();
 20 |   });
 21 | 
 22 |   test('throws on non-element binding', async () => {
 23 |     try {
 24 |       const callback = (): void => {
 25 |         return;
 26 |       };
 27 |       element.template = () => html`
 28 |         <div>${onLongPress(callback)}</div>
 29 |       `;
 30 |       await element.updateComplete;
 31 |       assert.unreachable();
 32 |     } catch (err) {
 33 |       assert.is(
 34 |         (err as Error).message,
 35 |         'The `onLongPress` directive must be used in an element binding'
 36 |       );
 37 |     }
 38 |   });
 39 | 
 40 |   test('calls callback after timeout', async () => {
 41 |     const callback = hanbi.spy();
 42 |     element.template = () => html`
 43 |       <div ${onLongPress(callback.handler, 10)}></div>
 44 |     `;
 45 |     await element.updateComplete;
 46 | 
 47 |     const div = element.shadowRoot!.querySelector('div')!;
 48 |     const ev = new PointerEvent('pointerdown');
 49 | 
 50 |     div.dispatchEvent(ev);
 51 |     await delay(12);
 52 | 
 53 |     assert.equal(callback.called, true);
 54 |     assert.equal(callback.firstCall!.args, [ev]);
 55 |   });
 56 | 
 57 |   test('does not call callback if pointer up before timer', async () => {
 58 |     const callback = hanbi.spy();
 59 |     element.template = () => html`
 60 |       <div ${onLongPress(callback.handler, 10)}></div>
 61 |     `;
 62 |     await element.updateComplete;
 63 | 
 64 |     const div = element.shadowRoot!.querySelector('div')!;
 65 |     const pointerDown = new PointerEvent('pointerdown');
 66 |     const pointerUp = new PointerEvent('pointerup');
 67 | 
 68 |     div.dispatchEvent(pointerDown);
 69 |     await delay(5);
 70 |     div.dispatchEvent(pointerUp);
 71 |     await delay(10);
 72 | 
 73 |     assert.equal(callback.called, false);
 74 |   });
 75 | 
 76 |   test('does not call callback if pointer leaves before timer', async () => {
 77 |     const callback = hanbi.spy();
 78 |     element.template = () => html`
 79 |       <div ${onLongPress(callback.handler, 10)}></div>
 80 |     `;
 81 |     await element.updateComplete;
 82 | 
 83 |     const div = element.shadowRoot!.querySelector('div')!;
 84 |     const pointerDown = new PointerEvent('pointerdown');
 85 |     const pointerLeave = new PointerEvent('pointerleave');
 86 | 
 87 |     div.dispatchEvent(pointerDown);
 88 |     await delay(5);
 89 |     div.dispatchEvent(pointerLeave);
 90 |     await delay(10);
 91 | 
 92 |     assert.equal(callback.called, false);
 93 |   });
 94 | 
 95 |   test('does not call callback if disconnected', async () => {
 96 |     const callback = hanbi.spy();
 97 |     element.template = () => html`
 98 |       <div ${onLongPress(callback.handler, 10)}></div>
 99 |     `;
100 |     await element.updateComplete;
101 | 
102 |     const div = element.shadowRoot!.querySelector('div')!;
103 |     const ev = new PointerEvent('pointerdown');
104 | 
105 |     element.remove();
106 | 
107 |     div.dispatchEvent(ev);
108 |     await delay(12);
109 | 
110 |     assert.equal(callback.called, false);
111 |   });
112 | 
113 |   test('survives reconnection to dom', async () => {
114 |     const callback = hanbi.spy();
115 |     element.template = () => html`
116 |       <div ${onLongPress(callback.handler, 10)}></div>
117 |     `;
118 |     await element.updateComplete;
119 | 
120 |     const div = element.shadowRoot!.querySelector('div')!;
121 |     const ev = new PointerEvent('pointerdown');
122 | 
123 |     element.remove();
124 |     document.body.appendChild(element);
125 |     await element.updateComplete;
126 | 
127 |     div.dispatchEvent(ev);
128 |     await delay(12);
129 | 
130 |     assert.equal(callback.called, true);
131 |   });
132 | 
133 |   test('applies default timeout if none set', async () => {
134 |     const callback = hanbi.spy();
135 |     element.template = () => html`
136 |       <div ${onLongPress(callback.handler)}></div>
137 |     `;
138 |     await element.updateComplete;
139 | 
140 |     const div = element.shadowRoot!.querySelector('div')!;
141 |     const ev = new PointerEvent('pointerdown');
142 | 
143 |     div.dispatchEvent(ev);
144 |     await delay(500);
145 | 
146 |     assert.equal(callback.called, false);
147 | 
148 |     await delay(600);
149 | 
150 |     assert.equal(callback.called, true);
151 |   });
152 | });
153 | 


--------------------------------------------------------------------------------
/src/test/util.ts:
--------------------------------------------------------------------------------
 1 | import {LitElement, html, css} from 'lit';
 2 | import type {
 3 |   ReactiveController,
 4 |   TemplateResult,
 5 |   PropertyDeclarations
 6 | } from 'lit';
 7 | 
 8 | type TestTemplateFn = () => TemplateResult;
 9 | 
10 | /**
11 |  * Base of all test elements
12 |  */
13 | export abstract class TestElementBase extends LitElement {
14 |   public static override styles = css`
15 |     :host {
16 |       display: block;
17 |     }
18 |   `;
19 | 
20 |   /** @inheritdoc */
21 |   public static override get properties(): PropertyDeclarations {
22 |     return {
23 |       template: {type: Object}
24 |     };
25 |   }
26 | 
27 |   public controllers: ReactiveController[] = [];
28 |   public template?: TestTemplateFn;
29 | 
30 |   /** @inheritdoc */
31 |   protected override render(): TemplateResult {
32 |     return this.template?.() ?? html``;
33 |   }
34 | }
35 | 
36 | /**
37 |  * Test element with controllers
38 |  */
39 | export class TestElement extends TestElementBase {}
40 | 
41 | customElements.define('test-element', TestElement);
42 | 
43 | export async function delay(timeoutMs: number): Promise<void> {
44 |   await new Promise((r) => setTimeout(r, timeoutMs));
45 | }
46 | 
47 | declare global {
48 |   interface HTMLElementTagNameMap {
49 |     'test-element': TestElement;
50 |   }
51 | }
52 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "target": "es2022",
 4 |     "module": "es2022",
 5 |     "moduleResolution": "node",
 6 |     "declaration": true,
 7 |     "outDir": "./lib",
 8 |     "importHelpers": true,
 9 |     "forceConsistentCasingInFileNames": true,
10 |     "types": ["mocha"],
11 |     "strict": true,
12 |     "noImplicitAny": true,
13 |     "strictNullChecks": true,
14 |     "strictFunctionTypes": true,
15 |     "strictBindCallApply": true,
16 |     "strictPropertyInitialization": true,
17 |     "noImplicitThis": true,
18 |     "useUnknownInCatchVariables": true,
19 |     "alwaysStrict": true,
20 |     "noUnusedLocals": true,
21 |     "noUnusedParameters": true,
22 |     "exactOptionalPropertyTypes": true,
23 |     "noImplicitReturns": true,
24 |     "noFallthroughCasesInSwitch": true,
25 |     "noUncheckedIndexedAccess": true,
26 |     "noImplicitOverride": true,
27 |     "noPropertyAccessFromIndexSignature": true,
28 |     "useDefineForClassFields": false
29 |   },
30 |   "include": ["src/**/*.ts"]
31 | }
32 | 


--------------------------------------------------------------------------------
/web-test-runner.config.mjs:
--------------------------------------------------------------------------------
 1 | import {puppeteerLauncher} from '@web/test-runner-puppeteer';
 2 | import {esbuildPlugin} from '@web/dev-server-esbuild';
 3 | 
 4 | export default {
 5 |   nodeResolve: true,
 6 |   files: ['src/**/*_test.ts'],
 7 |   coverage: true,
 8 |   coverageConfig: {
 9 |     reporters: ['lcov']
10 |   },
11 |   browsers: [
12 |     puppeteerLauncher({concurrency: 1})
13 |   ],
14 |   plugins: [
15 |     esbuildPlugin({
16 |       ts: true,
17 |       target: 'auto',
18 |       tsconfig: './tsconfig.json'
19 |     })
20 |   ],
21 |   testFramework: {
22 |     config: {
23 |       ui: 'tdd'
24 |     }
25 |   }
26 | };
27 | 


--------------------------------------------------------------------------------