shelving 1.305.0 → 1.307.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/db/store/QueryStore.d.ts +84 -7
- package/db/store/QueryStore.js +248 -34
- package/package.json +1 -1
- package/ui/style/TINT_CLASS.md +17 -0
- package/ui/style/Tint.d.ts +2 -1
- package/ui/style/Tint.js +3 -2
- package/ui/style/Tint.tsx +3 -2
- package/util/query.d.ts +27 -6
- package/util/query.js +49 -28
package/db/store/QueryStore.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { FetchStore } from "../../store/FetchStore.js";
|
|
2
|
-
import type
|
|
2
|
+
import { type Data } from "../../util/data.js";
|
|
3
3
|
import type { Identifier, Item, Items } from "../../util/item.js";
|
|
4
4
|
import { type Query } from "../../util/query.js";
|
|
5
5
|
import type { Collection } from "../collection/Collection.js";
|
|
@@ -9,7 +9,10 @@ import type { MemoryDBProvider } from "../provider/MemoryDBProvider.js";
|
|
|
9
9
|
* Store that runs a query against a collection from a database provider and tracks its matching items.
|
|
10
10
|
*
|
|
11
11
|
* - Holds an `Items` value (the array of matching items) and is iterable over those items.
|
|
12
|
-
* - Seeds from a `MemoryDBProvider` snapshot when available, and
|
|
12
|
+
* - Seeds from a `MemoryDBProvider` snapshot when available, and follows changes in the memory.
|
|
13
|
+
* - A query with an `$order` loads in pages: `fetchAfter()` loads the next page at the end, and `fetchBefore()` loads new items at the start.
|
|
14
|
+
* - A query with an `$order` pins its items: each item keeps its position after a fetch, so an edit never moves an item or removes it from view. A deleted item is hidden. New items in the memory that sort before the first item show at the start at once (e.g. an optimistic preview).
|
|
15
|
+
* - A query without an `$order` follows the live query result in the memory, and cannot page.
|
|
13
16
|
*
|
|
14
17
|
* @example
|
|
15
18
|
* const store = new QueryStore(collection, query, provider);
|
|
@@ -32,17 +35,35 @@ export declare class QueryStore<I extends Identifier, T extends Data> extends Fe
|
|
|
32
35
|
* @see https://shelving.cc/db/QueryStore/query
|
|
33
36
|
*/
|
|
34
37
|
readonly query: Query<Item<I, T>>;
|
|
38
|
+
/**
|
|
39
|
+
* The memory provider this store seeds from and follows, if available.
|
|
40
|
+
* @see https://shelving.cc/db/QueryStore/memory
|
|
41
|
+
*/
|
|
42
|
+
readonly memory: MemoryDBProvider<I> | undefined;
|
|
35
43
|
/**
|
|
36
44
|
* The maximum number of items the query can return, or `Infinity` if unlimited.
|
|
45
|
+
* - For a paged query, this is the size of each page.
|
|
37
46
|
* @see https://shelving.cc/db/QueryStore/limit
|
|
38
47
|
*/
|
|
39
48
|
get limit(): number;
|
|
40
49
|
/**
|
|
41
|
-
* Whether more items can be loaded after the
|
|
50
|
+
* Whether more items can be loaded after the last item with `fetchAfter()`.
|
|
51
|
+
* @see https://shelving.cc/db/QueryStore/hasAfter
|
|
52
|
+
*/
|
|
53
|
+
get hasAfter(): boolean;
|
|
54
|
+
private _hasAfter;
|
|
55
|
+
/**
|
|
56
|
+
* Whether more items can be loaded before the first item with `fetchBefore()`.
|
|
57
|
+
* - `false` after the first fetch, because the first page starts at the start. It becomes `true` when `fetchBefore()` finds more new items than one page.
|
|
58
|
+
* @see https://shelving.cc/db/QueryStore/hasBefore
|
|
59
|
+
*/
|
|
60
|
+
get hasBefore(): boolean;
|
|
61
|
+
private _hasBefore;
|
|
62
|
+
/**
|
|
63
|
+
* Whether more items can be loaded after the last item. Alias of `hasAfter`.
|
|
42
64
|
* @see https://shelving.cc/db/QueryStore/hasMore
|
|
43
65
|
*/
|
|
44
66
|
get hasMore(): boolean;
|
|
45
|
-
private _hasMore;
|
|
46
67
|
/**
|
|
47
68
|
* The first item in this store, or `undefined` if the query has no items.
|
|
48
69
|
* @see https://shelving.cc/db/QueryStore/optionalFirst
|
|
@@ -71,12 +92,68 @@ export declare class QueryStore<I extends Identifier, T extends Data> extends Fe
|
|
|
71
92
|
* @see https://shelving.cc/db/QueryStore/last
|
|
72
93
|
*/
|
|
73
94
|
get last(): Item<I, T>;
|
|
95
|
+
private readonly _orders;
|
|
96
|
+
private readonly _filters;
|
|
97
|
+
private _ids;
|
|
98
|
+
private _rows;
|
|
99
|
+
private _loaded;
|
|
100
|
+
private _generation;
|
|
74
101
|
constructor(collection: Collection<string, I, T>, query: Query<Item<I, T>>, provider: DBProvider<I>, memory?: MemoryDBProvider<I>);
|
|
75
102
|
_fetch(_signal: AbortSignal): Promise<Items<I, T>>;
|
|
76
103
|
/**
|
|
77
|
-
* Load
|
|
78
|
-
* -
|
|
79
|
-
*
|
|
104
|
+
* Load the next page of items after the last item.
|
|
105
|
+
* - Uses the query `$limit` as the page size.
|
|
106
|
+
* - Sets `busy` while the page loads. The items already loaded do not suspend.
|
|
107
|
+
* - Waits for a fetch that is already running, then loads the page.
|
|
108
|
+
* - Does nothing if `hasAfter` is `false`.
|
|
109
|
+
* - Loads the first page if no items have loaded yet.
|
|
110
|
+
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
111
|
+
*
|
|
112
|
+
* @returns Promise that resolves when the page has loaded.
|
|
113
|
+
* @throws {RequiredError} If the query has no `$order`.
|
|
114
|
+
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
115
|
+
* @example if (store.hasAfter) await store.fetchAfter();
|
|
116
|
+
* @see https://shelving.cc/db/QueryStore/fetchAfter
|
|
117
|
+
*/
|
|
118
|
+
fetchAfter(): Promise<void>;
|
|
119
|
+
/**
|
|
120
|
+
* Load the next page of items after the last item. Alias of `fetchAfter()`.
|
|
121
|
+
*
|
|
122
|
+
* @returns Promise that resolves when the page has loaded.
|
|
123
|
+
* @see https://shelving.cc/db/QueryStore/fetchMore
|
|
124
|
+
*/
|
|
125
|
+
fetchMore(): Promise<void>;
|
|
126
|
+
/**
|
|
127
|
+
* Load the new items before the first item, e.g. new messages at the start of a newest-first list.
|
|
128
|
+
* - Loads up to one page (the query `$limit`), nearest to the first item. Call again while `hasBefore` is `true` to load more.
|
|
129
|
+
* - Sets `busy` while the items load. The items already loaded do not suspend.
|
|
130
|
+
* - Waits for a fetch that is already running, then loads the items.
|
|
131
|
+
* - Loads the first page if no items have loaded yet.
|
|
132
|
+
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
133
|
+
*
|
|
134
|
+
* @returns Promise that resolves when the new items have loaded.
|
|
135
|
+
* @throws {RequiredError} If the query has no `$order`.
|
|
136
|
+
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
137
|
+
* @example setInterval(() => store.fetchBefore().catch(BLACKHOLE), 10_000); // Poll for new messages.
|
|
138
|
+
* @see https://shelving.cc/db/QueryStore/fetchBefore
|
|
139
|
+
*/
|
|
140
|
+
fetchBefore(): Promise<void>;
|
|
141
|
+
/** Wait until no fetch is running. */
|
|
142
|
+
private _idle;
|
|
143
|
+
/** Fetch one page from an inclusive cursor query, and drop the items already loaded. */
|
|
144
|
+
private _fetchPage;
|
|
145
|
+
/** Pin a list of items (or IDs of items already pinned) as the loaded items, in display order. */
|
|
146
|
+
private _pin;
|
|
147
|
+
/** Get a pinned item as it was fetched. */
|
|
148
|
+
private _getRow;
|
|
149
|
+
/**
|
|
150
|
+
* Make the current value of a paged query.
|
|
151
|
+
* - New items in the memory that match the filters and sort before the first pinned item come first.
|
|
152
|
+
* - When the list is complete (`hasAfter` is `false`), new items that sort after the last pinned item come last.
|
|
153
|
+
* - Then each pinned item in its pinned position, with its current data from the memory. Items deleted from the memory are hidden.
|
|
80
154
|
*/
|
|
155
|
+
private _compose;
|
|
156
|
+
/** Recompose the value after the memory changes. */
|
|
157
|
+
private _recompose;
|
|
81
158
|
[Symbol.iterator](): Iterator<Item<I, T>>;
|
|
82
159
|
}
|
package/db/store/QueryStore.js
CHANGED
|
@@ -1,15 +1,21 @@
|
|
|
1
1
|
import { RequiredError } from "../../error/RequiredError.js";
|
|
2
2
|
import { FetchStore } from "../../store/FetchStore.js";
|
|
3
|
-
import { getFirst, getLast } from "../../util/array.js";
|
|
3
|
+
import { getFirst, getLast, requireFirst } from "../../util/array.js";
|
|
4
4
|
import { getGetter } from "../../util/class.js";
|
|
5
5
|
import { NONE } from "../../util/constants.js";
|
|
6
|
-
import {
|
|
6
|
+
import { getDataProp, joinDataPath } from "../../util/data.js";
|
|
7
|
+
import { isEqual } from "../../util/equal.js";
|
|
8
|
+
import { compareQueryItems, getAfterQuery, getBeforeQuery, getQueryFilters, getQueryLimit, getQueryOrders, matchQueryItem, sortQueryItems, } from "../../util/query.js";
|
|
7
9
|
import { runSequence } from "../../util/sequence.js";
|
|
10
|
+
import { isDefined } from "../../util/undefined.js";
|
|
8
11
|
/**
|
|
9
12
|
* Store that runs a query against a collection from a database provider and tracks its matching items.
|
|
10
13
|
*
|
|
11
14
|
* - Holds an `Items` value (the array of matching items) and is iterable over those items.
|
|
12
|
-
* - Seeds from a `MemoryDBProvider` snapshot when available, and
|
|
15
|
+
* - Seeds from a `MemoryDBProvider` snapshot when available, and follows changes in the memory.
|
|
16
|
+
* - A query with an `$order` loads in pages: `fetchAfter()` loads the next page at the end, and `fetchBefore()` loads new items at the start.
|
|
17
|
+
* - A query with an `$order` pins its items: each item keeps its position after a fetch, so an edit never moves an item or removes it from view. A deleted item is hidden. New items in the memory that sort before the first item show at the start at once (e.g. an optimistic preview).
|
|
18
|
+
* - A query without an `$order` follows the live query result in the memory, and cannot page.
|
|
13
19
|
*
|
|
14
20
|
* @example
|
|
15
21
|
* const store = new QueryStore(collection, query, provider);
|
|
@@ -32,21 +38,43 @@ export class QueryStore extends FetchStore {
|
|
|
32
38
|
* @see https://shelving.cc/db/QueryStore/query
|
|
33
39
|
*/
|
|
34
40
|
query;
|
|
41
|
+
/**
|
|
42
|
+
* The memory provider this store seeds from and follows, if available.
|
|
43
|
+
* @see https://shelving.cc/db/QueryStore/memory
|
|
44
|
+
*/
|
|
45
|
+
memory;
|
|
35
46
|
/**
|
|
36
47
|
* The maximum number of items the query can return, or `Infinity` if unlimited.
|
|
48
|
+
* - For a paged query, this is the size of each page.
|
|
37
49
|
* @see https://shelving.cc/db/QueryStore/limit
|
|
38
50
|
*/
|
|
39
51
|
get limit() {
|
|
40
52
|
return getQueryLimit(this.query) ?? Number.POSITIVE_INFINITY;
|
|
41
53
|
}
|
|
42
54
|
/**
|
|
43
|
-
* Whether more items can be loaded after the
|
|
55
|
+
* Whether more items can be loaded after the last item with `fetchAfter()`.
|
|
56
|
+
* @see https://shelving.cc/db/QueryStore/hasAfter
|
|
57
|
+
*/
|
|
58
|
+
get hasAfter() {
|
|
59
|
+
return this._hasAfter;
|
|
60
|
+
}
|
|
61
|
+
_hasAfter = false;
|
|
62
|
+
/**
|
|
63
|
+
* Whether more items can be loaded before the first item with `fetchBefore()`.
|
|
64
|
+
* - `false` after the first fetch, because the first page starts at the start. It becomes `true` when `fetchBefore()` finds more new items than one page.
|
|
65
|
+
* @see https://shelving.cc/db/QueryStore/hasBefore
|
|
66
|
+
*/
|
|
67
|
+
get hasBefore() {
|
|
68
|
+
return this._hasBefore;
|
|
69
|
+
}
|
|
70
|
+
_hasBefore = false;
|
|
71
|
+
/**
|
|
72
|
+
* Whether more items can be loaded after the last item. Alias of `hasAfter`.
|
|
44
73
|
* @see https://shelving.cc/db/QueryStore/hasMore
|
|
45
74
|
*/
|
|
46
75
|
get hasMore() {
|
|
47
|
-
return this.
|
|
76
|
+
return this._hasAfter;
|
|
48
77
|
}
|
|
49
|
-
_hasMore = false;
|
|
50
78
|
/**
|
|
51
79
|
* The first item in this store, or `undefined` if the query has no items.
|
|
52
80
|
* @see https://shelving.cc/db/QueryStore/optionalFirst
|
|
@@ -101,44 +129,230 @@ export class QueryStore extends FetchStore {
|
|
|
101
129
|
});
|
|
102
130
|
return last;
|
|
103
131
|
}
|
|
132
|
+
// Paging state (only used when the query has an `$order`).
|
|
133
|
+
_orders;
|
|
134
|
+
_filters;
|
|
135
|
+
_ids = []; // Pinned IDs in display order.
|
|
136
|
+
_rows = new Map(); // Pinned items as they were fetched (their sort values are the cursors).
|
|
137
|
+
_loaded = false; // Whether any items have been pinned yet.
|
|
138
|
+
_generation = 0; // Increases when a refresh starts.
|
|
104
139
|
constructor(collection, query, provider, memory) {
|
|
105
140
|
const items = memory?.getTable(collection).getQuery(query);
|
|
106
141
|
super(items ?? NONE); // Use the current memory snapshot if available.
|
|
107
|
-
if (memory)
|
|
108
|
-
this.starter = store => runSequence(store.through(memory.getQuerySequence(collection, query)));
|
|
109
142
|
this.provider = provider;
|
|
110
143
|
this.collection = collection;
|
|
111
144
|
this.query = query;
|
|
145
|
+
this.memory = memory;
|
|
146
|
+
this._orders = getQueryOrders(query);
|
|
147
|
+
this._filters = getQueryFilters(query);
|
|
148
|
+
if (this._orders.length) {
|
|
149
|
+
// Paged query: pin the snapshot, and recompose the pinned items whenever the memory changes.
|
|
150
|
+
if (items) {
|
|
151
|
+
this._pin(items);
|
|
152
|
+
this._hasAfter = items.length >= this.limit; // A full snapshot may have more items after it.
|
|
153
|
+
}
|
|
154
|
+
if (memory)
|
|
155
|
+
this.starter = store => runSequence(memory.getQuerySequence(collection), () => store._recompose());
|
|
156
|
+
}
|
|
157
|
+
else if (memory) {
|
|
158
|
+
// Unpaged query: follow the live query result in the memory.
|
|
159
|
+
this.starter = store => runSequence(store.through(memory.getQuerySequence(collection, query)));
|
|
160
|
+
}
|
|
112
161
|
}
|
|
113
162
|
// Override to fetch the result from the database provider.
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
163
|
+
// - A paged query loads the first page again, and drops any other loaded pages.
|
|
164
|
+
async _fetch(_signal) {
|
|
165
|
+
if (!this._orders.length)
|
|
166
|
+
return this.provider.getQuery(this.collection, this.query);
|
|
167
|
+
const { collection, query, limit } = this;
|
|
168
|
+
const generation = ++this._generation; // Makes any page fetch that is still running drop its result.
|
|
169
|
+
// Load one more item than the page, to see if there are more.
|
|
170
|
+
const items = await this.provider.getQuery(collection, _withLimit(query, limit + 1));
|
|
171
|
+
if (generation !== this._generation)
|
|
172
|
+
return this._compose(); // A newer refresh started, so it sets the items.
|
|
173
|
+
this._hasAfter = items.length > limit;
|
|
174
|
+
this._hasBefore = false;
|
|
175
|
+
this._pin(items.slice(0, limit));
|
|
176
|
+
return this._compose();
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Load the next page of items after the last item.
|
|
180
|
+
* - Uses the query `$limit` as the page size.
|
|
181
|
+
* - Sets `busy` while the page loads. The items already loaded do not suspend.
|
|
182
|
+
* - Waits for a fetch that is already running, then loads the page.
|
|
183
|
+
* - Does nothing if `hasAfter` is `false`.
|
|
184
|
+
* - Loads the first page if no items have loaded yet.
|
|
185
|
+
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
186
|
+
*
|
|
187
|
+
* @returns Promise that resolves when the page has loaded.
|
|
188
|
+
* @throws {RequiredError} If the query has no `$order`.
|
|
189
|
+
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
190
|
+
* @example if (store.hasAfter) await store.fetchAfter();
|
|
191
|
+
* @see https://shelving.cc/db/QueryStore/fetchAfter
|
|
192
|
+
*/
|
|
193
|
+
async fetchAfter() {
|
|
194
|
+
const { query, limit } = this;
|
|
195
|
+
if (!this._orders.length)
|
|
196
|
+
throw new RequiredError("Query must have $order to fetch more items", { store: this, query, caller: this.fetchAfter });
|
|
197
|
+
if (this.busy.value)
|
|
198
|
+
await this._idle(); // Only await when busy, so `busy` is set at once.
|
|
199
|
+
const last = this._getRow(this._ids.at(-1));
|
|
200
|
+
if (!last) {
|
|
201
|
+
await this.refresh();
|
|
202
|
+
return;
|
|
203
|
+
}
|
|
204
|
+
if (!this._hasAfter)
|
|
205
|
+
return;
|
|
206
|
+
const items = await this._fetchPage(getAfterQuery(query, last, this.fetchAfter), last);
|
|
207
|
+
if (!items)
|
|
208
|
+
return;
|
|
209
|
+
this._hasAfter = items.length > limit;
|
|
210
|
+
this._pin([...this._ids, ...items.slice(0, limit)]);
|
|
211
|
+
this.write(this._compose());
|
|
212
|
+
}
|
|
213
|
+
/**
|
|
214
|
+
* Load the next page of items after the last item. Alias of `fetchAfter()`.
|
|
215
|
+
*
|
|
216
|
+
* @returns Promise that resolves when the page has loaded.
|
|
217
|
+
* @see https://shelving.cc/db/QueryStore/fetchMore
|
|
218
|
+
*/
|
|
219
|
+
fetchMore() {
|
|
220
|
+
return this.fetchAfter();
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* Load the new items before the first item, e.g. new messages at the start of a newest-first list.
|
|
224
|
+
* - Loads up to one page (the query `$limit`), nearest to the first item. Call again while `hasBefore` is `true` to load more.
|
|
225
|
+
* - Sets `busy` while the items load. The items already loaded do not suspend.
|
|
226
|
+
* - Waits for a fetch that is already running, then loads the items.
|
|
227
|
+
* - Loads the first page if no items have loaded yet.
|
|
228
|
+
* - A failed fetch rejects the promise, and the items already loaded stay. Unlike `refresh()`, it does not set `reason`.
|
|
229
|
+
*
|
|
230
|
+
* @returns Promise that resolves when the new items have loaded.
|
|
231
|
+
* @throws {RequiredError} If the query has no `$order`.
|
|
232
|
+
* @throws {unknown} The error from the provider, if the fetch fails.
|
|
233
|
+
* @example setInterval(() => store.fetchBefore().catch(BLACKHOLE), 10_000); // Poll for new messages.
|
|
234
|
+
* @see https://shelving.cc/db/QueryStore/fetchBefore
|
|
235
|
+
*/
|
|
236
|
+
async fetchBefore() {
|
|
237
|
+
const { query, limit } = this;
|
|
238
|
+
if (!this._orders.length)
|
|
239
|
+
throw new RequiredError("Query must have $order to fetch more items", { store: this, query, caller: this.fetchBefore });
|
|
240
|
+
if (this.busy.value)
|
|
241
|
+
await this._idle(); // Only await when busy, so `busy` is set at once.
|
|
242
|
+
const first = this._getRow(this._ids[0]);
|
|
243
|
+
if (!first) {
|
|
244
|
+
await this.refresh();
|
|
245
|
+
return;
|
|
246
|
+
}
|
|
247
|
+
// Reverse the order so the items nearest to the first item come first.
|
|
248
|
+
const items = await this._fetchPage({ ...getBeforeQuery(query, first, this.fetchBefore), $order: _reverseOrders(this._orders) }, first);
|
|
249
|
+
if (!items)
|
|
250
|
+
return;
|
|
251
|
+
this._hasBefore = items.length > limit;
|
|
252
|
+
this._pin([...items.slice(0, limit).reverse(), ...this._ids]);
|
|
253
|
+
this.write(this._compose());
|
|
254
|
+
}
|
|
255
|
+
/** Wait until no fetch is running. */
|
|
256
|
+
async _idle() {
|
|
257
|
+
while (this.busy.value)
|
|
258
|
+
await this.busy.next;
|
|
259
|
+
}
|
|
260
|
+
/** Fetch one page from an inclusive cursor query, and drop the items already loaded. */
|
|
261
|
+
async _fetchPage(query, cursor) {
|
|
262
|
+
const { _ids, _rows, limit } = this;
|
|
263
|
+
const { key } = requireFirst(this._orders);
|
|
264
|
+
const value = getDataProp(cursor, key);
|
|
265
|
+
// The inclusive range returns the loaded items with the same sort value as the cursor again, so ask for that many more.
|
|
266
|
+
let ties = 0;
|
|
267
|
+
for (const id of _ids) {
|
|
268
|
+
const row = _rows.get(id);
|
|
269
|
+
if (row && isEqual(getDataProp(row, key), value))
|
|
270
|
+
ties++;
|
|
271
|
+
}
|
|
272
|
+
// A refresh that starts while the page loads owns the items and `busy`, so the page is dropped.
|
|
273
|
+
const generation = this._generation;
|
|
274
|
+
this.busy.value = true;
|
|
275
|
+
try {
|
|
276
|
+
const items = await this.provider.getQuery(this.collection, _withLimit(query, limit + ties + 1));
|
|
277
|
+
if (generation !== this._generation)
|
|
278
|
+
return;
|
|
279
|
+
const seen = new Set(_ids);
|
|
280
|
+
return items.filter(({ id }) => !seen.has(id));
|
|
281
|
+
}
|
|
282
|
+
catch (thrown) {
|
|
283
|
+
if (generation === this._generation)
|
|
284
|
+
throw thrown; // Keep the loaded items, so do not set `reason`.
|
|
285
|
+
}
|
|
286
|
+
finally {
|
|
287
|
+
if (generation === this._generation)
|
|
288
|
+
this.busy.value = false;
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
/** Pin a list of items (or IDs of items already pinned) as the loaded items, in display order. */
|
|
292
|
+
_pin(items) {
|
|
293
|
+
const rows = new Map();
|
|
294
|
+
const ids = [];
|
|
295
|
+
for (const item of items) {
|
|
296
|
+
const row = typeof item === "object" ? item : this._rows.get(item);
|
|
297
|
+
if (!row || rows.has(row.id))
|
|
298
|
+
continue;
|
|
299
|
+
rows.set(row.id, row);
|
|
300
|
+
ids.push(row.id);
|
|
301
|
+
}
|
|
302
|
+
this._ids = ids;
|
|
303
|
+
this._rows = rows;
|
|
304
|
+
this._loaded = true;
|
|
305
|
+
// Put the fetched items in the memory, so other stores can use them.
|
|
306
|
+
if (this.memory)
|
|
307
|
+
this.memory.getTable(this.collection).setItems(items.filter(item => typeof item === "object"));
|
|
308
|
+
}
|
|
309
|
+
/** Get a pinned item as it was fetched. */
|
|
310
|
+
_getRow(id) {
|
|
311
|
+
return id === undefined ? undefined : this._rows.get(id);
|
|
312
|
+
}
|
|
313
|
+
/**
|
|
314
|
+
* Make the current value of a paged query.
|
|
315
|
+
* - New items in the memory that match the filters and sort before the first pinned item come first.
|
|
316
|
+
* - When the list is complete (`hasAfter` is `false`), new items that sort after the last pinned item come last.
|
|
317
|
+
* - Then each pinned item in its pinned position, with its current data from the memory. Items deleted from the memory are hidden.
|
|
318
|
+
*/
|
|
319
|
+
_compose() {
|
|
320
|
+
const { memory, _ids, _rows, _orders, _filters } = this;
|
|
321
|
+
if (!memory)
|
|
322
|
+
return _ids.map(id => _rows.get(id)).filter(isDefined);
|
|
323
|
+
const table = memory.getTable(this.collection);
|
|
324
|
+
const first = this._getRow(_ids[0]);
|
|
325
|
+
const last = this._hasAfter ? undefined : this._getRow(_ids.at(-1)); // Only a complete list shows new items at the end.
|
|
326
|
+
const head = [];
|
|
327
|
+
const tail = [];
|
|
328
|
+
for (const item of table.getQuery()) {
|
|
329
|
+
if (_rows.has(item.id) || !matchQueryItem(item, _filters))
|
|
330
|
+
continue;
|
|
331
|
+
if (!first || compareQueryItems(item, first, _orders) < 0)
|
|
332
|
+
head.push(item);
|
|
333
|
+
else if (last && compareQueryItems(item, last, _orders) > 0)
|
|
334
|
+
tail.push(item);
|
|
335
|
+
}
|
|
336
|
+
const body = _ids.map(id => table.getItem(id)).filter(isDefined);
|
|
337
|
+
return [...sortQueryItems(head, _orders), ...body, ...sortQueryItems(tail, _orders)];
|
|
338
|
+
}
|
|
339
|
+
/** Recompose the value after the memory changes. */
|
|
340
|
+
_recompose() {
|
|
341
|
+
// Skip while loading, or while a fetch runs (it recomposes when it ends, and a write now would abort a refresh).
|
|
342
|
+
if (!this._loaded || this.busy.value)
|
|
343
|
+
return;
|
|
344
|
+
this.write(this._compose());
|
|
345
|
+
}
|
|
140
346
|
// Implement `Iterable`
|
|
141
347
|
[Symbol.iterator]() {
|
|
142
348
|
return this.value.values();
|
|
143
349
|
}
|
|
144
350
|
}
|
|
351
|
+
/** Set the limit of a query, or remove it when the limit is infinite. */
|
|
352
|
+
function _withLimit(query, limit) {
|
|
353
|
+
return { ...query, $limit: Number.isFinite(limit) ? limit : undefined }; // Not `withProp()`, because it cannot infer `$limit` on a generic `Query<T>`.
|
|
354
|
+
}
|
|
355
|
+
/** Reverse every order of a query. */
|
|
356
|
+
function _reverseOrders(orders) {
|
|
357
|
+
return orders.map(({ key, direction }) => `${direction === "asc" ? "!" : ""}${joinDataPath(key)}`);
|
|
358
|
+
}
|
package/package.json
CHANGED
package/ui/style/TINT_CLASS.md
CHANGED
|
@@ -48,4 +48,21 @@ A theme is a CSS file of custom-property overrides at `:root`, imported after th
|
|
|
48
48
|
2. **Retint a region.** Apply `color=` / `status=` to a container — `<Card color="purple">`, or a `<Panel color="purple">` wrapping a whole section — and everything inside re-tints, with text, border, surface, and hover shades all derived for free. Components don't expose a per-component `--x-tint` hook; the variant moves the anchor, not a bespoke variable.
|
|
49
49
|
3. **Override one property.** Per-property hooks are the scalpel: `--button-radius: 999px`, `--card-radius: 0`, `--tag-case: none`.
|
|
50
50
|
|
|
51
|
+
**Overrides that use ladder steps go on `:root, .tint`.** A `var()` inside a custom property resolves where the property is declared. So an override at `:root` alone locks in the `:root` ladder, and stays grey inside a `<Card color="red">`:
|
|
52
|
+
|
|
53
|
+
```css
|
|
54
|
+
/* Wrong: `--tint-95` resolves once, at `:root`. */
|
|
55
|
+
:root {
|
|
56
|
+
--table-border: 2px solid var(--tint-95);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/* Right: the value resolves again in every scope that rebuilds the ladder. */
|
|
60
|
+
:root,
|
|
61
|
+
.tint {
|
|
62
|
+
--table-border: 2px solid var(--tint-95);
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`TINT_CLASS` adds a plain global `tint` class (as well as its hashed module class) for this purpose, so `tint` is a reserved class name. Do not use `* { … }` for this: it declares the variable on every element, which adds style-recalc cost on large pages.
|
|
67
|
+
|
|
51
68
|
**Don't override individual ladder steps (`--tint-90`, etc.) at `:root`.** The ladder is *recomputed* from the anchor inside every `TINT_CLASS` scope — which includes every component that accepts `color=` or `status=` — so a step override at `:root` only reaches untinted regions and produces inconsistent surfaces. Move the anchor (option 1 or 2) instead, and the steps follow.
|
package/ui/style/Tint.d.ts
CHANGED
|
@@ -10,7 +10,8 @@ export type TintVariant = "00" | "05" | "10" | "15" | "20" | "25" | "30" | "35"
|
|
|
10
10
|
* CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
|
|
11
11
|
*
|
|
12
12
|
* - Applied by colour/status helpers so an element can compose shades like `--tint-20` and `--tint-95` of the selected hue.
|
|
13
|
+
* - Also adds the plain global `tint` class, so theme files can target the recompute scope with `:root, .tint { … }`.
|
|
13
14
|
*
|
|
14
15
|
* @see https://shelving.cc/ui/TINT_CLASS
|
|
15
16
|
*/
|
|
16
|
-
export declare const TINT_CLASS: string
|
|
17
|
+
export declare const TINT_CLASS: string;
|
package/ui/style/Tint.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
|
-
import { getModuleClass } from "../util/css.js";
|
|
1
|
+
import { getClass, getModuleClass } from "../util/css.js";
|
|
2
2
|
import THEME_CSS from "./Tint.module.css";
|
|
3
3
|
/**
|
|
4
4
|
* CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
|
|
5
5
|
*
|
|
6
6
|
* - Applied by colour/status helpers so an element can compose shades like `--tint-20` and `--tint-95` of the selected hue.
|
|
7
|
+
* - Also adds the plain global `tint` class, so theme files can target the recompute scope with `:root, .tint { … }`.
|
|
7
8
|
*
|
|
8
9
|
* @see https://shelving.cc/ui/TINT_CLASS
|
|
9
10
|
*/
|
|
10
|
-
export const TINT_CLASS = getModuleClass(THEME_CSS, "tint");
|
|
11
|
+
export const TINT_CLASS = getClass("tint", getModuleClass(THEME_CSS, "tint"));
|
package/ui/style/Tint.tsx
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { getModuleClass } from "../util/css.js";
|
|
1
|
+
import { getClass, getModuleClass } from "../util/css.js";
|
|
2
2
|
import THEME_CSS from "./Tint.module.css";
|
|
3
3
|
|
|
4
4
|
/**
|
|
@@ -36,7 +36,8 @@ export type TintVariant =
|
|
|
36
36
|
* CSS class that (re)calculates the full ladder of tint shades from the current global tint colour.
|
|
37
37
|
*
|
|
38
38
|
* - Applied by colour/status helpers so an element can compose shades like `--tint-20` and `--tint-95` of the selected hue.
|
|
39
|
+
* - Also adds the plain global `tint` class, so theme files can target the recompute scope with `:root, .tint { … }`.
|
|
39
40
|
*
|
|
40
41
|
* @see https://shelving.cc/ui/TINT_CLASS
|
|
41
42
|
*/
|
|
42
|
-
export const TINT_CLASS = getModuleClass(THEME_CSS, "tint");
|
|
43
|
+
export const TINT_CLASS = getClass("tint", getModuleClass(THEME_CSS, "tint"));
|
package/util/query.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { ImmutableArray } from "./array.js";
|
|
2
2
|
import type { Data, LeafData, LeafDataPath } from "./data.js";
|
|
3
|
+
import type { AnyCaller } from "./function.js";
|
|
3
4
|
import type { Segments } from "./string.js";
|
|
4
5
|
/**
|
|
5
6
|
* Query that can be applied to a list of data objects.
|
|
@@ -141,12 +142,32 @@ export declare function sortQueryItems<T extends Data>(items: Iterable<T>, order
|
|
|
141
142
|
/** LImit a set of data items using a set of limit. */
|
|
142
143
|
export declare function limitQueryItems<T extends Data>(items: ImmutableArray<T> | Iterable<T>, limit: number | undefined): Iterable<T>;
|
|
143
144
|
/**
|
|
144
|
-
* Get a query for items that
|
|
145
|
-
* - For
|
|
145
|
+
* Get a query for the items that sort at or before a specified item.
|
|
146
|
+
* - For cursor-based paging towards the start of a result set.
|
|
147
|
+
* - Adds an inclusive range on the first `$order` key only (`key<=` for an ascending order, `key>=` for a descending order), so items with the same value as `item` are included. Drop the items you already have by ID.
|
|
148
|
+
* - Keeps the existing order and limit. To get the nearest items first, reverse the order before you set a limit.
|
|
149
|
+
* - Page on a first key with many distinct values (e.g. a timestamp). Many items with the same value make each page read them all again.
|
|
150
|
+
*
|
|
151
|
+
* @param query The query to page through. It must have an `$order`.
|
|
152
|
+
* @param item The item to page from (normally the first item already loaded).
|
|
153
|
+
* @returns A new query with the range added.
|
|
154
|
+
* @throws {RequiredError} If the query has no `$order`, or `item` has no value for the first `$order` key.
|
|
155
|
+
* @example getBeforeQuery({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when>=": 5 }
|
|
156
|
+
* @see https://shelving.cc/util/query/getBeforeQuery
|
|
146
157
|
*/
|
|
147
|
-
export declare function getBeforeQuery<T extends Data>(query: Query<T>, item: T): Query<T>;
|
|
158
|
+
export declare function getBeforeQuery<T extends Data>(query: Query<T>, item: T, caller?: AnyCaller): Query<T>;
|
|
148
159
|
/**
|
|
149
|
-
* Get a query for items that
|
|
150
|
-
* - For
|
|
160
|
+
* Get a query for the items that sort at or after a specified item.
|
|
161
|
+
* - For cursor-based paging towards the end of a result set.
|
|
162
|
+
* - Adds an inclusive range on the first `$order` key only (`key>=` for an ascending order, `key<=` for a descending order), so items with the same value as `item` are included. Drop the items you already have by ID.
|
|
163
|
+
* - Keeps the existing order and limit.
|
|
164
|
+
* - Page on a first key with many distinct values (e.g. a timestamp). Many items with the same value make each page read them all again.
|
|
165
|
+
*
|
|
166
|
+
* @param query The query to page through. It must have an `$order`.
|
|
167
|
+
* @param item The item to page from (normally the last item already loaded).
|
|
168
|
+
* @returns A new query with the range added.
|
|
169
|
+
* @throws {RequiredError} If the query has no `$order`, or `item` has no value for the first `$order` key.
|
|
170
|
+
* @example getAfterQuery({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when<=": 5 }
|
|
171
|
+
* @see https://shelving.cc/util/query/getAfterQuery
|
|
151
172
|
*/
|
|
152
|
-
export declare function getAfterQuery<T extends Data>(query: Query<T>, item: T): Query<T>;
|
|
173
|
+
export declare function getAfterQuery<T extends Data>(query: Query<T>, item: T, caller?: AnyCaller): Query<T>;
|
package/util/query.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { RequiredError } from "../error/RequiredError.js";
|
|
2
|
+
import { isArray, limitArray, requireFirst } from "./array.js";
|
|
2
3
|
import { getDataProp, joinDataPath, splitDataPath } from "./data.js";
|
|
3
4
|
import { isArrayWith, isEqual, isEqualGreater, isEqualLess, isGreater, isInArray, isLess, notEqual, notInArray } from "./equal.js";
|
|
4
5
|
import { limitItems } from "./iterate.js";
|
|
@@ -156,36 +157,56 @@ export function limitQueryItems(items, limit) {
|
|
|
156
157
|
return typeof limit !== "number" ? items : isArray(items) ? limitArray(items, limit) : limitItems(items, limit);
|
|
157
158
|
}
|
|
158
159
|
/**
|
|
159
|
-
* Get a query for items that
|
|
160
|
-
* - For
|
|
160
|
+
* Get a query for the items that sort at or before a specified item.
|
|
161
|
+
* - For cursor-based paging towards the start of a result set.
|
|
162
|
+
* - Adds an inclusive range on the first `$order` key only (`key<=` for an ascending order, `key>=` for a descending order), so items with the same value as `item` are included. Drop the items you already have by ID.
|
|
163
|
+
* - Keeps the existing order and limit. To get the nearest items first, reverse the order before you set a limit.
|
|
164
|
+
* - Page on a first key with many distinct values (e.g. a timestamp). Many items with the same value make each page read them all again.
|
|
165
|
+
*
|
|
166
|
+
* @param query The query to page through. It must have an `$order`.
|
|
167
|
+
* @param item The item to page from (normally the first item already loaded).
|
|
168
|
+
* @returns A new query with the range added.
|
|
169
|
+
* @throws {RequiredError} If the query has no `$order`, or `item` has no value for the first `$order` key.
|
|
170
|
+
* @example getBeforeQuery({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when>=": 5 }
|
|
171
|
+
* @see https://shelving.cc/util/query/getBeforeQuery
|
|
161
172
|
*/
|
|
162
|
-
export function getBeforeQuery(query, item) {
|
|
163
|
-
const
|
|
164
|
-
|
|
165
|
-
const newQuery = { ...query };
|
|
166
|
-
for (const sort of sorts) {
|
|
167
|
-
const { key, direction } = sort;
|
|
168
|
-
const keyStr = joinDataPath(key);
|
|
169
|
-
const value = getDataProp(item, key);
|
|
170
|
-
newQuery[direction === "asc" ? (sort === lastSort ? `${keyStr}>` : `${keyStr}>=`) : sort === lastSort ? `${keyStr}<` : `${keyStr}<=`] =
|
|
171
|
-
value;
|
|
172
|
-
}
|
|
173
|
-
return newQuery;
|
|
173
|
+
export function getBeforeQuery(query, item, caller = getBeforeQuery) {
|
|
174
|
+
const { key, direction } = requireFirst(getQueryOrders(query), caller);
|
|
175
|
+
return _withRange(query, key, direction === "asc" ? "<=" : ">=", _requireCursor(item, key, caller));
|
|
174
176
|
}
|
|
175
177
|
/**
|
|
176
|
-
* Get a query for items that
|
|
177
|
-
* - For
|
|
178
|
+
* Get a query for the items that sort at or after a specified item.
|
|
179
|
+
* - For cursor-based paging towards the end of a result set.
|
|
180
|
+
* - Adds an inclusive range on the first `$order` key only (`key>=` for an ascending order, `key<=` for a descending order), so items with the same value as `item` are included. Drop the items you already have by ID.
|
|
181
|
+
* - Keeps the existing order and limit.
|
|
182
|
+
* - Page on a first key with many distinct values (e.g. a timestamp). Many items with the same value make each page read them all again.
|
|
183
|
+
*
|
|
184
|
+
* @param query The query to page through. It must have an `$order`.
|
|
185
|
+
* @param item The item to page from (normally the last item already loaded).
|
|
186
|
+
* @returns A new query with the range added.
|
|
187
|
+
* @throws {RequiredError} If the query has no `$order`, or `item` has no value for the first `$order` key.
|
|
188
|
+
* @example getAfterQuery({ $order: "!when" }, { id: "a", when: 5 }) // { $order: "!when", "when<=": 5 }
|
|
189
|
+
* @see https://shelving.cc/util/query/getAfterQuery
|
|
178
190
|
*/
|
|
179
|
-
export function getAfterQuery(query, item) {
|
|
180
|
-
const
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
191
|
+
export function getAfterQuery(query, item, caller = getAfterQuery) {
|
|
192
|
+
const { key, direction } = requireFirst(getQueryOrders(query), caller);
|
|
193
|
+
return _withRange(query, key, direction === "asc" ? ">=" : "<=", _requireCursor(item, key, caller));
|
|
194
|
+
}
|
|
195
|
+
/** Get the cursor value of an item, or throw if it has none (a range on `undefined` would be dropped). */
|
|
196
|
+
function _requireCursor(item, key, caller) {
|
|
197
|
+
const value = getDataProp(item, key);
|
|
198
|
+
if (value === undefined)
|
|
199
|
+
throw new RequiredError(`Item must have a value for "${joinDataPath(key)}"`, { item, caller });
|
|
200
|
+
return value;
|
|
201
|
+
}
|
|
202
|
+
/** Add an inclusive range to a query, but keep an existing range on the same key when it is narrower. */
|
|
203
|
+
function _withRange(query, key, operator, value) {
|
|
204
|
+
const prop = `${joinDataPath(key)}${operator}`;
|
|
205
|
+
const current = query[prop];
|
|
206
|
+
if (current !== undefined) {
|
|
207
|
+
const c = compareAscending(current, value);
|
|
208
|
+
if (operator === "<=" ? c <= 0 : c >= 0)
|
|
209
|
+
return query;
|
|
189
210
|
}
|
|
190
|
-
return
|
|
211
|
+
return { ...query, [prop]: value };
|
|
191
212
|
}
|