Rewrite ItemList; update ItemList typings (#3005)

* Improve typings for ItemList

* Add new `.replace()` syntax

* Update JSDoc

* Add missing `T` type

* Fix typo

Co-authored-by: Alexander Skvortsov <38059171+askvortsov1@users.noreply.github.com>

* Allow choice to not set `itemName` property when calling `toArray`

* Make `ItemList.items` read-only

* Modify `.replace()`; add `.changePriority()`

* Complete rename

* Update JSDoc

* Add `.toObject()` method; deprecate `.items`

* Rewrite `.toArray()` to use Proxy instead of modifying the item content

- Fixes #3030
- Fixes issue where setting `itemName` property could result in errors depending on the object type (e.g. proxies)
- Fixes unneeded duplication of item list
- Add option to disable setting `itemName` property on primitives

* Simplify condition

* Remove debug code

* Make proxying function protected instead of private

* Update a usage of ItemList as an example

* Make `itemName` property read-only

* Use correct capitalisation of `object`

* Invert `toArray` parameter function

* Simplify isEmpty check

* Update ItemList.ts

* Fix `merge()`

* Remove extra JSDoc comment

* Use `._items` directly for merging

* Rename methods: `replace` -> `set`; `changePriority` -> `setPriority`

This more closely matches our existing method names (`get()`)

* Change `items` getter

* Simplify proxying

* Update URL to source function

* Update compat

* Various changes to toObject

* Remove `Item.key`

* Make item content proxy method private

* Enforce merge typings

* Update TSDoc comments to use `{@link}` for references to methods

* Correct references to deprecated `.replace` method

* Throw error when setting content/priority of non-existent items

* Remove intermediary variable

* Update TSDoc block

* Update js/src/@types/global.d.ts

Co-authored-by: Alexander Skvortsov <38059171+askvortsov1@users.noreply.github.com>

js/src/@types/global.d.ts

@@ -1,3 +1,8 @@
+declare type Writable<T> = { -readonly [P in keyof T]: T[P] };
+declare type DeepWritable<T> = { -readonly [P in keyof T]: DeepWritable<T[P]> };
+
+declare type DeepReadonly<T> = { readonly [P in keyof T]: DeepReadonly<T[P]> };
+
 /**
  * UTILITY TYPES
  */

js/src/admin/components/UserListPage.tsx

@@ -14,6 +14,7 @@ import classList from '../../common/utils/classList';
 import extractText from '../../common/utils/extractText';
 
 import AdminPage from './AdminPage';
+import Mithril from 'mithril';
 
 type ColumnData = {
   /**
@@ -97,7 +98,7 @@ export default class UserListPage extends AdminPage {
       ];
     }
 
-    const columns: (ColumnData & { itemName: string })[] = this.columns().toArray();
+    const columns = this.columns().toArray();
 
     return [
       <p class="UserListPage-totalUsers">{app.translator.trans('core.admin.users.total_users', { count: this.userCount })}</p>,
@@ -177,7 +178,7 @@ export default class UserListPage extends AdminPage {
    *
    * See `UserListPage.tsx` for examples.
    */
-  columns(): ItemList {
+  columns(): ItemList<ColumnData> {
     const columns = new ItemList();
 
     columns.add(

js/src/common/compat.js

@@ -79,6 +79,7 @@ import listItems from './helpers/listItems';
 import Fragment from './Fragment';
 import DefaultResolver from './resolvers/DefaultResolver';
 import PaginatedListState from './states/PaginatedListState';
+import isObject from './utils/isObject';
 
 export default {
   extend: extend,
@@ -114,6 +115,7 @@ export default {
   'utils/mapRoutes': mapRoutes,
   'utils/withAttr': withAttr,
   'utils/throttleDebounce': ThrottleDebounce,
+  'utils/isObject': isObject,
   'models/Notification': Notification,
   'models/User': User,
   'models/Post': Post,