@iebh/tera-fy 1.5.0 → 1.6.1

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.
Files changed (10) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/api.md +457 -417
  3. package/dist/plugin.vue2.es2019.js +1 -1
  4. package/dist/terafy.es2019.js +2 -2
  5. package/dist/terafy.js +1 -1
  6. package/lib/projectFile.js +25 -4
  7. package/lib/terafy.client.js +39 -10
  8. package/lib/terafy.server.js +73 -40
  9. package/package.json +6 -3
  10. package/plugins/vue2.js +5 -3
package/api.md CHANGED
@@ -7,128 +7,132 @@
7
7
  * [name][3]
8
8
  * [icon][4]
9
9
  * [path][5]
10
- * [parsedName][6]
11
- * [Properties][7]
12
- * [created][8]
13
- * [createdFormatted][9]
14
- * [modified][10]
15
- * [modifiedFormatted][11]
16
- * [accessed][12]
17
- * [accessedFormatted][13]
18
- * [size][14]
19
- * [sizeFormatted][15]
20
- * [mime][16]
21
- * [meta][17]
22
- * [getContents][18]
23
- * [setContents][19]
24
- * [Parameters][20]
25
- * [getRefs][21]
26
- * [setRefs][22]
27
- * [Parameters][23]
28
- * [serialize][24]
29
- * [deserialize][25]
30
- * [Parameters][26]
31
- * [tera][27]
32
- * [Parameters][28]
33
- * [TeraFy][29]
34
- * [settings][30]
35
- * [Properties][31]
36
- * [events][32]
37
- * [dom][33]
38
- * [Properties][34]
39
- * [methods][35]
40
- * [plugins][36]
41
- * [send][37]
42
- * [Parameters][38]
43
- * [sendRaw][39]
10
+ * [url][6]
11
+ * [teraUrl][7]
12
+ * [parsedName][8]
13
+ * [Properties][9]
14
+ * [created][10]
15
+ * [createdFormatted][11]
16
+ * [modified][12]
17
+ * [modifiedFormatted][13]
18
+ * [accessed][14]
19
+ * [accessedFormatted][15]
20
+ * [size][16]
21
+ * [sizeFormatted][17]
22
+ * [mime][18]
23
+ * [meta][19]
24
+ * [getContents][20]
25
+ * [setContents][21]
26
+ * [Parameters][22]
27
+ * [getRefs][23]
28
+ * [setRefs][24]
29
+ * [Parameters][25]
30
+ * [serialize][26]
31
+ * [deserialize][27]
32
+ * [Parameters][28]
33
+ * [tera][29]
34
+ * [Parameters][30]
35
+ * [TeraFy][31]
36
+ * [settings][32]
37
+ * [Properties][33]
38
+ * [events][34]
39
+ * [dom][35]
40
+ * [Properties][36]
41
+ * [methods][37]
42
+ * [plugins][38]
43
+ * [send][39]
44
44
  * [Parameters][40]
45
- * [rpc][41]
45
+ * [sendRaw][41]
46
46
  * [Parameters][42]
47
- * [acceptMessage][43]
47
+ * [rpc][43]
48
48
  * [Parameters][44]
49
- * [acceptPostboxes][45]
50
- * [createProjectStatePatch][46]
51
- * [Parameters][47]
52
- * [applyProjectStatePatchLocal][48]
49
+ * [acceptMessage][45]
50
+ * [Parameters][46]
51
+ * [acceptPostboxes][47]
52
+ * [createProjectStatePatch][48]
53
53
  * [Parameters][49]
54
- * [init][50]
54
+ * [applyProjectStatePatchLocal][50]
55
55
  * [Parameters][51]
56
- * [detectMode][52]
57
- * [injectComms][53]
58
- * [injectStylesheet][54]
59
- * [injectMethods][55]
60
- * [debug][56]
61
- * [Parameters][57]
62
- * [set][58]
56
+ * [init][52]
57
+ * [Parameters][53]
58
+ * [detectMode][54]
59
+ * [injectComms][55]
60
+ * [injectStylesheet][56]
61
+ * [injectMethods][57]
62
+ * [debug][58]
63
63
  * [Parameters][59]
64
- * [setIfDev][60]
64
+ * [set][60]
65
65
  * [Parameters][61]
66
- * [use][62]
66
+ * [setIfDev][62]
67
67
  * [Parameters][63]
68
- * [mixin][64]
68
+ * [use][64]
69
69
  * [Parameters][65]
70
- * [toggleDevMode][66]
70
+ * [mixin][66]
71
71
  * [Parameters][67]
72
- * [toggleFocus][68]
72
+ * [toggleDevMode][68]
73
73
  * [Parameters][69]
74
- * [selectProjectFile][70]
74
+ * [toggleFocus][70]
75
75
  * [Parameters][71]
76
- * [getProjectFiles][72]
76
+ * [selectProjectFile][72]
77
77
  * [Parameters][73]
78
- * [getProjectFile][74]
78
+ * [getProjectFiles][74]
79
79
  * [Parameters][75]
80
- * [handshake][76]
81
- * [Properties][77]
82
- * [User][78]
80
+ * [getProjectFile][76]
81
+ * [Parameters][77]
82
+ * [handshake][78]
83
83
  * [Properties][79]
84
- * [getUser][80]
85
- * [requireUser][81]
86
- * [Parameters][82]
87
- * [Project][83]
88
- * [getProject][84]
89
- * [getProjects][85]
90
- * [setActiveProject][86]
91
- * [Parameters][87]
92
- * [requireProject][88]
84
+ * [User][80]
85
+ * [Properties][81]
86
+ * [getUser][82]
87
+ * [requireUser][83]
88
+ * [Parameters][84]
89
+ * [Project][85]
90
+ * [getProject][86]
91
+ * [getProjects][87]
92
+ * [setActiveProject][88]
93
93
  * [Parameters][89]
94
- * [selectProject][90]
94
+ * [requireProject][90]
95
95
  * [Parameters][91]
96
- * [getProjectState][92]
96
+ * [selectProject][92]
97
97
  * [Parameters][93]
98
- * [setProjectState][94]
98
+ * [getProjectState][94]
99
99
  * [Parameters][95]
100
- * [setProjectStateDefaults][96]
100
+ * [setProjectState][96]
101
101
  * [Parameters][97]
102
- * [saveProjectState][98]
103
- * [replaceProjectState][99]
104
- * [Parameters][100]
105
- * [applyProjectStatePatch][101]
106
- * [Parameters][102]
107
- * [subscribeProjectState][103]
108
- * [FileFilters][104]
109
- * [Properties][105]
110
- * [selectProjectFile][106]
111
- * [Parameters][107]
112
- * [setProjectFile][108]
113
- * [Parameters][109]
114
- * [selectProjectLibrary][110]
102
+ * [setProjectStateDefaults][98]
103
+ * [Parameters][99]
104
+ * [setProjectStateFlush][100]
105
+ * [setProjectStateRefresh][101]
106
+ * [saveProjectState][102]
107
+ * [replaceProjectState][103]
108
+ * [Parameters][104]
109
+ * [applyProjectStatePatch][105]
110
+ * [Parameters][106]
111
+ * [subscribeProjectState][107]
112
+ * [FileFilters][108]
113
+ * [Properties][109]
114
+ * [selectProjectFile][110]
115
115
  * [Parameters][111]
116
- * [getProjectLibrary][112]
116
+ * [setProjectFile][112]
117
117
  * [Parameters][113]
118
- * [setProjectLibrary][114]
118
+ * [selectProjectLibrary][114]
119
119
  * [Parameters][115]
120
- * [projectLog][116]
120
+ * [getProjectLibrary][116]
121
121
  * [Parameters][117]
122
- * [setPageUrl][118]
122
+ * [setProjectLibrary][118]
123
123
  * [Parameters][119]
124
- * [setPageTitle][120]
124
+ * [projectLog][120]
125
125
  * [Parameters][121]
126
- * [uiAlert][122]
126
+ * [setPageUrl][122]
127
127
  * [Parameters][123]
128
- * [uiSplat][124]
128
+ * [setPageTitle][124]
129
129
  * [Parameters][125]
130
- * [uiWindow][126]
130
+ * [uiAlert][126]
131
131
  * [Parameters][127]
132
+ * [uiSplat][128]
133
+ * [Parameters][129]
134
+ * [uiWindow][130]
135
+ * [Parameters][131]
132
136
 
133
137
  ## ProjectFile
134
138
 
@@ -138,99 +142,113 @@ A project file fetched from TERA
138
142
 
139
143
  A UUID string representing the unique ID of the file
140
144
 
141
- Type: [String][128]
145
+ Type: [String][132]
142
146
 
143
147
  ### name
144
148
 
145
149
  Relative name path (can contain prefix directories) for the human readable file name
146
150
 
147
- Type: [String][128]
151
+ Type: [String][132]
148
152
 
149
153
  ### icon
150
154
 
151
155
  CSS class to use as the file icon
152
156
 
153
- Type: [String][128]
157
+ Type: [String][132]
154
158
 
155
159
  ### path
156
160
 
157
161
  Full path to the file
158
162
  This is also used as the unique identifier within the project
159
163
 
160
- Type: [String][128]
164
+ Type: [String][132]
165
+
166
+ ### url
167
+
168
+ Fully qualified URL to view / access / download the file from TERA
169
+ This will usually open an edit UI within the TERA site
170
+
171
+ Type: [String][132]
172
+
173
+ ### teraUrl
174
+
175
+ Rewrite of the URL where the absolute URL has been removed in place of a relative path, assuming the owner project is active
176
+ This is used to direct to the edit/view/download UI when the files project is active and is usually used in place of URL for TERA related operations
177
+
178
+ Type: [String][132]
161
179
 
162
180
  ### parsedName
163
181
 
164
182
  An object representing meta file parts of a file name
165
183
 
166
- Type: [Object][129]
184
+ Type: [Object][133]
167
185
 
168
186
  #### Properties
169
187
 
170
- * `basename` **[String][128]** The filename + extention (i.e. everything without directory name)
171
- * `filename` **[String][128]** The file portion of the name (basename without the extension)
172
- * `ext` **[String][128]** The extension portion of the name (always lower case)
173
- * `dirName` **[String][128]** The directory path portion of the name
188
+ * `basename` **[String][132]** The filename + extention (i.e. everything without directory name)
189
+ * `filename` **[String][132]** The file portion of the name (basename without the extension)
190
+ * `ext` **[String][132]** The extension portion of the name (always lower case)
191
+ * `dirName` **[String][132]** The directory path portion of the name
174
192
 
175
193
  ### created
176
194
 
177
195
  A date representing when the file was created
178
196
 
179
- Type: [Date][130]
197
+ Type: [Date][134]
180
198
 
181
199
  ### createdFormatted
182
200
 
183
201
  A human readable, formatted version of "created"
184
202
 
185
- Type: [String][128]
203
+ Type: [String][132]
186
204
 
187
205
  ### modified
188
206
 
189
207
  A date representing when the file was created
190
208
 
191
- Type: [Date][130]
209
+ Type: [Date][134]
192
210
 
193
211
  ### modifiedFormatted
194
212
 
195
213
  A human readable, formatted version of "modified"
196
214
 
197
- Type: [String][128]
215
+ Type: [String][132]
198
216
 
199
217
  ### accessed
200
218
 
201
219
  A date representing when the file was last accessed
202
220
 
203
- Type: [Date][130]
221
+ Type: [Date][134]
204
222
 
205
223
  ### accessedFormatted
206
224
 
207
225
  A human readable, formatted version of "accessed"
208
226
 
209
- Type: [String][128]
227
+ Type: [String][132]
210
228
 
211
229
  ### size
212
230
 
213
231
  Size, in bytes, of the file
214
232
 
215
- Type: [Number][131]
233
+ Type: [Number][135]
216
234
 
217
235
  ### sizeFormatted
218
236
 
219
237
  A human readable, formatted version of the file size
220
238
 
221
- Type: [String][128]
239
+ Type: [String][132]
222
240
 
223
241
  ### mime
224
242
 
225
243
  The associated mime type for the file
226
244
 
227
- Type: [String][128]
245
+ Type: [String][132]
228
246
 
229
247
  ### meta
230
248
 
231
249
  Additional meta information for the file
232
250
 
233
- Type: [Object][129]
251
+ Type: [Object][133]
234
252
 
235
253
  ### getContents
236
254
 
@@ -248,9 +266,9 @@ Overwrite the contents of a file with new content
248
266
 
249
267
  #### Parameters
250
268
 
251
- * `contents` **(File | [Blob][132] | [FormData][133] | [Object][129] | [Array][134])** The new file contents
269
+ * `contents` **(File | [Blob][136] | [FormData][137] | [Object][133] | [Array][138])** The new file contents
252
270
 
253
- Returns **[Promise][135]** A promise which resolves when the operation has completed
271
+ Returns **[Promise][139]** A promise which resolves when the operation has completed
254
272
 
255
273
  ### getRefs
256
274
 
@@ -258,7 +276,7 @@ Returns **[Promise][135]** A promise which resolves when the operation has compl
258
276
 
259
277
  Fetch the file contents as an array of Reflib refs
260
278
 
261
- Returns **[Promise][135]<[Array][134]\<Ref>>** An eventual array of RefLib references
279
+ Returns **[Promise][139]<[Array][138]\<Ref>>** An eventual array of RefLib references
262
280
 
263
281
  ### setRefs
264
282
 
@@ -269,18 +287,18 @@ Overwrite the contents of a file with a new collection of Reflib refs
269
287
  #### Parameters
270
288
 
271
289
  * `refs` &#x20;
272
- * `Collection` **[Array][134]\<RefLibRef>** of references for the selected library
290
+ * `Collection` **[Array][138]\<RefLibRef>** of references for the selected library
273
291
 
274
- Returns **[Promise][135]** A promise which resolves when the operation has completed
292
+ Returns **[Promise][139]** A promise which resolves when the operation has completed
275
293
 
276
294
  ### serialize
277
295
 
278
- * **See**: [https://developer.mozilla.org/en-US/docs/Web/API/Web\_Workers\_API/Structured\_clone\_algorithm][136]
296
+ * **See**: [https://developer.mozilla.org/en-US/docs/Web/API/Web\_Workers\_API/Structured\_clone\_algorithm][140]
279
297
 
280
298
  Compress a file state down into a serializable entity
281
299
  By default this computes a Structured Clone which can be stringified
282
300
 
283
- Returns **[Object][129]** A Structured Clone compatible representation of this ProjectFile instance
301
+ Returns **[Object][133]** A Structured Clone compatible representation of this ProjectFile instance
284
302
 
285
303
  ### deserialize
286
304
 
@@ -288,7 +306,7 @@ Restore an entity created with serialize
288
306
 
289
307
  #### Parameters
290
308
 
291
- * `data` **[Object][129]** An input object created via `ProjectFiles.serialize()`
309
+ * `data` **[Object][133]** An input object created via `ProjectFiles.serialize()`
292
310
 
293
311
  Returns **[ProjectFile][1]** A ProjectFile instance setup against the deserializzed data
294
312
 
@@ -308,19 +326,19 @@ Main Tera-Fy Client (class singleton) to be used in a frontend browser
308
326
 
309
327
  Various settings to configure behaviour
310
328
 
311
- Type: [Object][129]
329
+ Type: [Object][133]
312
330
 
313
331
  #### Properties
314
332
 
315
- * `devMode` **[Boolean][137]** Operate in devMode - i.e. force outer refresh when encountering an existing TeraFy instance
316
- * `verbosity` **[Number][131]** Verbosity level, the higher the more chatty TeraFY will be. Set to zero to disable all `debug()` call output
333
+ * `devMode` **[Boolean][141]** Operate in devMode - i.e. force outer refresh when encountering an existing TeraFy instance
334
+ * `verbosity` **[Number][135]** Verbosity level, the higher the more chatty TeraFY will be. Set to zero to disable all `debug()` call output
317
335
  * `mode` **(`"detect"` | `"parent"` | `"child"` | `"popup"`)** How to communicate with TERA. 'parent' assumes that the parent of the current document is TERA, 'child' spawns an iFrame and uses TERA there, 'detect' tries parent and switches to `modeFallback` if communication fails
318
- * `modeFallback` **[String][128]** Method to use when all method detection fails
319
- * `modeTimeout` **[Number][131]** How long entities have in 'detect' mode to identify themselves
320
- * `siteUrl` **[String][128]** The TERA URL to connect to
321
- * `restrictOrigin` **[String][128]** URL to restrict communications to
322
- * `List` **[Array][134]<[String][128]>** of sandbox allowables for the embedded if in embed mode
323
- * `handshakeInterval` **[Number][131]** Interval in milliseconds when sanning for a handshake
336
+ * `modeFallback` **[String][132]** Method to use when all method detection fails
337
+ * `modeTimeout` **[Number][135]** How long entities have in 'detect' mode to identify themselves
338
+ * `siteUrl` **[String][132]** The TERA URL to connect to
339
+ * `restrictOrigin` **[String][132]** URL to restrict communications to
340
+ * `List` **[Array][138]<[String][132]>** of sandbox allowables for the embedded if in embed mode
341
+ * `handshakeInterval` **[Number][135]** Interval in milliseconds when sanning for a handshake
324
342
 
325
343
  ### events
326
344
 
@@ -332,13 +350,13 @@ Type: Mitt
332
350
 
333
351
  DOMElements for this TeraFy instance
334
352
 
335
- Type: [Object][129]
353
+ Type: [Object][133]
336
354
 
337
355
  #### Properties
338
356
 
339
357
  * `el` **DOMElement** The main tera-fy div wrapper
340
358
  * `iframe` **DOMElement** The internal iFrame element (if `settings.mode == 'child'`)
341
- * `popup` **[Window][138]** The popup window context (if `settings.mode == 'popup'`)
359
+ * `popup` **[Window][142]** The popup window context (if `settings.mode == 'popup'`)
342
360
  * `stylesheet` **DOMElement** The corresponding stylesheet
343
361
 
344
362
  ### methods
@@ -346,13 +364,13 @@ Type: [Object][129]
346
364
  List of function stubs mapped from the server to here
347
365
  This array is forms the reference of `TeraFy.METHOD()` objects to provide locally which will be mapped via `TeraFy.rpc(METHOD, ...args)`
348
366
 
349
- Type: [Array][134]<[String][128]>
367
+ Type: [Array][138]<[String][132]>
350
368
 
351
369
  ### plugins
352
370
 
353
371
  Loaded plugins via Use()
354
372
 
355
- Type: [Array][134]\<TeraFyPlugin>
373
+ Type: [Array][138]\<TeraFyPlugin>
356
374
 
357
375
  ### send
358
376
 
@@ -360,9 +378,9 @@ Send a message + wait for a response object
360
378
 
361
379
  #### Parameters
362
380
 
363
- * `message` **[Object][129]** Message object to send
381
+ * `message` **[Object][133]** Message object to send
364
382
 
365
- Returns **[Promise][135]\<any>** A promise which resolves when the operation has completed with the remote reply
383
+ Returns **[Promise][139]\<any>** A promise which resolves when the operation has completed with the remote reply
366
384
 
367
385
  ### sendRaw
368
386
 
@@ -371,7 +389,7 @@ This function does not return or wait for a reply - use `send()` for that
371
389
 
372
390
  #### Parameters
373
391
 
374
- * `message` **[Object][129]** Message object to send
392
+ * `message` **[Object][133]** Message object to send
375
393
 
376
394
  ### rpc
377
395
 
@@ -379,10 +397,10 @@ Call an RPC function in the server instance
379
397
 
380
398
  #### Parameters
381
399
 
382
- * `method` **[String][128]** The method name to call
400
+ * `method` **[String][132]** The method name to call
383
401
  * `args` **...any**&#x20;
384
402
 
385
- Returns **[Promise][135]\<any>** The resolved output of the server function
403
+ Returns **[Promise][139]\<any>** The resolved output of the server function
386
404
 
387
405
  ### acceptMessage
388
406
 
@@ -391,7 +409,7 @@ Accept an incoming message
391
409
  #### Parameters
392
410
 
393
411
  * `rawMessage` &#x20;
394
- * `Raw` **[MessageEvent][139]** message event to process
412
+ * `Raw` **[MessageEvent][143]** message event to process
395
413
 
396
414
  ### acceptPostboxes
397
415
 
@@ -400,27 +418,27 @@ Listening postboxes, these correspond to outgoing message IDs that expect a resp
400
418
  ### createProjectStatePatch
401
419
 
402
420
  Create + transmit a new project state patch base on the current and previous states
403
- The transmitted patch follows the [JSPatch][140] standard
421
+ The transmitted patch follows the [JSPatch][144] standard
404
422
  This function accepts an entire projectState instance, computes the delta and transmits that to the server for merging
405
423
 
406
424
  #### Parameters
407
425
 
408
- * `newState` **[Object][129]** The local projectState to accept
409
- * `oldState` **[Object][129]** The previous projectState to examine against
426
+ * `newState` **[Object][133]** The local projectState to accept
427
+ * `oldState` **[Object][133]** The previous projectState to examine against
410
428
 
411
- Returns **[Promise][135]** A promise which will resolve when the operation has completed
429
+ Returns **[Promise][139]** A promise which will resolve when the operation has completed
412
430
 
413
431
  ### applyProjectStatePatchLocal
414
432
 
415
433
  Client function which accepts a patch from the server and applies it to local project state
416
- The patch should follow the [JSPatch][140] standard
434
+ The patch should follow the [JSPatch][144] standard
417
435
  This function is expected to be sub-classed by a plugin
418
436
 
419
437
  #### Parameters
420
438
 
421
- * `patch` **[Array][134]** A JSPatch patch to apply
439
+ * `patch` **[Array][138]** A JSPatch patch to apply
422
440
 
423
- Returns **[Promise][135]** A promise which will resolve when the operation has completed
441
+ Returns **[Promise][139]** A promise which will resolve when the operation has completed
424
442
 
425
443
  ### init
426
444
 
@@ -429,28 +447,28 @@ This function can only be called once and will return the existing init() worker
429
447
 
430
448
  #### Parameters
431
449
 
432
- * `options` **[Object][129]?** Additional options to merge into `settings` via `set`
450
+ * `options` **[Object][133]?** Additional options to merge into `settings` via `set`
433
451
 
434
- Returns **[Promise][135]<[TeraFy][29]>** An eventual promise which will resovle with this terafy instance
452
+ Returns **[Promise][139]<[TeraFy][31]>** An eventual promise which will resovle with this terafy instance
435
453
 
436
454
  ### detectMode
437
455
 
438
456
  Populate `settings.mode`
439
457
  Try to communicate with a parent frame, if none assume we need to fallback to child mode
440
458
 
441
- Returns **[Promise][135]<[String][128]>** A promise which will resolve with the detected mode to use
459
+ Returns **[Promise][139]<[String][132]>** A promise which will resolve with the detected mode to use
442
460
 
443
461
  ### injectComms
444
462
 
445
463
  Find an existing active TERA server OR initalize one
446
464
 
447
- Returns **[Promise][135]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
465
+ Returns **[Promise][139]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
448
466
 
449
467
  ### injectStylesheet
450
468
 
451
469
  Inject a local stylesheet to handle TERA server functionality
452
470
 
453
- Returns **[Promise][135]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
471
+ Returns **[Promise][139]** A promise which will resolve when the loading has completed and we have found a parent TERA instance or initiallized a child
454
472
 
455
473
  ### injectMethods
456
474
 
@@ -465,7 +483,7 @@ This function will only act if `settings.devMode` is truthy
465
483
 
466
484
  * `msg` **...any**&#x20;
467
485
  * `method` **(`"INFO"` | `"LOG"` | `"WARN"` | `"ERROR"`)** Logging method to use (optional, default `'LOG'`)
468
- * `verboseLevel` **[Number][131]** The verbosity level to trigger at. If `settings.verbosity` is lower than this, the message is ignored (optional, default `1`)
486
+ * `verboseLevel` **[Number][135]** The verbosity level to trigger at. If `settings.verbosity` is lower than this, the message is ignored (optional, default `1`)
469
487
 
470
488
  ### set
471
489
 
@@ -474,10 +492,10 @@ This function also routes 'special' keys like `devMode` to their internal handle
474
492
 
475
493
  #### Parameters
476
494
 
477
- * `key` **([String][128] | [Object][129])** Either a single setting key to set or an object to merge
495
+ * `key` **([String][132] | [Object][133])** Either a single setting key to set or an object to merge
478
496
  * `value` **any** The value to set if `key` is a string
479
497
 
480
- Returns **[TeraFy][29]** This chainable terafy instance
498
+ Returns **[TeraFy][31]** This chainable terafy instance
481
499
 
482
500
  ### setIfDev
483
501
 
@@ -487,10 +505,10 @@ Set or merge settings - but only in dev mode and only if the value is not undefi
487
505
 
488
506
  #### Parameters
489
507
 
490
- * `key` **([String][128] | [Object][129])** Either a single setting key to set or an object to merge
508
+ * `key` **([String][132] | [Object][133])** Either a single setting key to set or an object to merge
491
509
  * `value` **any** The value to set if `key` is a string
492
510
 
493
- Returns **[TeraFy][29]** This chainable terafy instance
511
+ Returns **[TeraFy][31]** This chainable terafy instance
494
512
 
495
513
  ### use
496
514
 
@@ -499,10 +517,10 @@ Include a TeraFy client plugin
499
517
  #### Parameters
500
518
 
501
519
  * `mod` &#x20;
502
- * `options` **[Object][129]?** Additional options to mutate behaviour during construction (pass options to init() to intialize later options)
503
- * `The` **[Object][129]** module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
520
+ * `options` **[Object][133]?** Additional options to mutate behaviour during construction (pass options to init() to intialize later options)
521
+ * `The` **[Object][133]** module function to include. Invoked as `(teraClient:TeraFy, options:Object)`
504
522
 
505
- Returns **[TeraFy][29]** This chainable terafy instance
523
+ Returns **[TeraFy][31]** This chainable terafy instance
506
524
 
507
525
  ### mixin
508
526
 
@@ -510,8 +528,8 @@ Internal function used by use() to merge an external declared singleton against
510
528
 
511
529
  #### Parameters
512
530
 
513
- * `target` **[Object][129]** Initalied class instance to extend
514
- * `source` **[Object][129]** Initalized source object to extend from
531
+ * `target` **[Object][133]** Initalied class instance to extend
532
+ * `source` **[Object][133]** Initalized source object to extend from
515
533
 
516
534
  ### toggleDevMode
517
535
 
@@ -519,9 +537,9 @@ Set or toggle devMode
519
537
 
520
538
  #### Parameters
521
539
 
522
- * `devModeEnabled` **([String][128] | [Boolean][137])** Optional boolean to force dev mode (optional, default `'toggle'`)
540
+ * `devModeEnabled` **([String][132] | [Boolean][141])** Optional boolean to force dev mode (optional, default `'toggle'`)
523
541
 
524
- Returns **[TeraFy][29]** This chainable terafy instance
542
+ Returns **[TeraFy][31]** This chainable terafy instance
525
543
 
526
544
  ### toggleFocus
527
545
 
@@ -530,7 +548,7 @@ This is usually because the server component wants to perform some user activity
530
548
 
531
549
  #### Parameters
532
550
 
533
- * `isFocused` **([String][128] | [Boolean][137])** Whether to fullscreen the embedded component (optional, default `'toggle'`)
551
+ * `isFocused` **([String][132] | [Boolean][141])** Whether to fullscreen the embedded component (optional, default `'toggle'`)
534
552
 
535
553
  ### selectProjectFile
536
554
 
@@ -542,7 +560,7 @@ This is an pre-requisite step for requireProject()
542
560
 
543
561
  * `options` &#x20;
544
562
 
545
- Returns **[Promise][135]** A promise which will resolve if the there is a user and they are logged in
563
+ Returns **[Promise][139]** A promise which will resolve if the there is a user and they are logged in
546
564
 
547
565
  ### getProjectFiles
548
566
 
@@ -550,12 +568,12 @@ Fetch the files associated with a given project
550
568
 
551
569
  #### Parameters
552
570
 
553
- * `options` **[Object][129]** Options which mutate behaviour
571
+ * `options` **[Object][133]** Options which mutate behaviour
554
572
 
555
- * `options.autoRequire` **[Boolean][137]** Run `requireProject()` automatically before continuing (optional, default `true`)
556
- * `options.meta` **[Boolean][137]** Pull meta information for each file entity (optional, default `true`)
573
+ * `options.autoRequire` **[Boolean][141]** Run `requireProject()` automatically before continuing (optional, default `true`)
574
+ * `options.meta` **[Boolean][141]** Pull meta information for each file entity (optional, default `true`)
557
575
 
558
- Returns **[Promise][135]<[Array][134]<[ProjectFile][1]>>** A collection of project files for the given project
576
+ Returns **[Promise][139]<[Array][138]<[ProjectFile][1]>>** A collection of project files for the given project
559
577
 
560
578
  ### getProjectFile
561
579
 
@@ -563,9 +581,9 @@ Fetch a project file
563
581
 
564
582
  #### Parameters
565
583
 
566
- * `path` **[String][128]** File path to read
584
+ * `id` **[String][132]** File ID to read
567
585
 
568
- Returns **[Promise][135]<[Blob][132]>** The eventual fetched file as a blob
586
+ Returns **[Promise][139]<[Blob][136]>** The eventual fetched file as a blob
569
587
 
570
588
  ## handshake
571
589
 
@@ -573,9 +591,9 @@ Return basic server information as a form of validation
573
591
 
574
592
  ### Properties
575
593
 
576
- * `date` **[Date][130]** Server date
594
+ * `date` **[Date][134]** Server date
577
595
 
578
- Returns **[Promise][135]<[Object][129]>** Basic promise result
596
+ Returns **[Promise][139]<[Object][133]>** Basic promise result
579
597
 
580
598
  ## User
581
599
 
@@ -583,16 +601,16 @@ User / active session within TERA
583
601
 
584
602
  ### Properties
585
603
 
586
- * `id` **[String][128]** Unique identifier of the user
587
- * `email` **[String][128]** The email address of the current user
588
- * `name` **[String][128]** The provided full name of the user
589
- * `isSubscribed` **[Boolean][137]** Whether the active user has a TERA subscription
604
+ * `id` **[String][132]** Unique identifier of the user
605
+ * `email` **[String][132]** The email address of the current user
606
+ * `name` **[String][132]** The provided full name of the user
607
+ * `isSubscribed` **[Boolean][141]** Whether the active user has a TERA subscription
590
608
 
591
609
  ## getUser
592
610
 
593
611
  Fetch the current session user
594
612
 
595
- Returns **[Promise][135]<[User][78]>** The current logged in user or null if none
613
+ Returns **[Promise][139]<[User][80]>** The current logged in user or null if none
596
614
 
597
615
  ## requireUser
598
616
 
@@ -602,11 +620,11 @@ This is an pre-requisite step for requireProject()
602
620
 
603
621
  ### Parameters
604
622
 
605
- * `options` **[Object][129]?** Additional options to mutate behaviour
623
+ * `options` **[Object][133]?** Additional options to mutate behaviour
606
624
 
607
- * `options.forceRetry` **[Boolean][137]** Forcabily try to refresh the user state (optional, default `false`)
625
+ * `options.forceRetry` **[Boolean][141]** Forcabily try to refresh the user state (optional, default `false`)
608
626
 
609
- Returns **[Promise][135]<[User][78]>** The current logged in user or null if none
627
+ Returns **[Promise][139]<[User][80]>** The current logged in user or null if none
610
628
 
611
629
  ## Project
612
630
 
@@ -616,13 +634,13 @@ Project entry within TERA
616
634
 
617
635
  Get the currently active project, if any
618
636
 
619
- Returns **[Promise][135]<([Project][83] | null)>** The currently active project, if any
637
+ Returns **[Promise][139]<([Project][85] | null)>** The currently active project, if any
620
638
 
621
639
  ## getProjects
622
640
 
623
641
  Get a list of projects the current session user has access to
624
642
 
625
- Returns **[Promise][135]<[Array][134]<[Project][83]>>** Collection of projects the user has access to
643
+ Returns **[Promise][139]<[Array][138]<[Project][85]>>** Collection of projects the user has access to
626
644
 
627
645
  ## setActiveProject
628
646
 
@@ -630,7 +648,7 @@ Set the currently active project within TERA
630
648
 
631
649
  ### Parameters
632
650
 
633
- * `project` **([Object][129] | [String][128])** The project to set as active - either the full Project object or its ID
651
+ * `project` **([Object][133] | [String][132])** The project to set as active - either the full Project object or its ID
634
652
 
635
653
  ## requireProject
636
654
 
@@ -639,14 +657,14 @@ Note that this function will percist in asking the uesr even if they try to canc
639
657
 
640
658
  ### Parameters
641
659
 
642
- * `options` **[Object][129]?** Additional options to mutate behaviour
660
+ * `options` **[Object][133]?** Additional options to mutate behaviour
643
661
 
644
- * `options.autoSetActiveProject` **[Boolean][137]** After selecting a project set that project as active in TERA (optional, default `true`)
645
- * `options.title` **[String][128]** The title of the dialog to display (optional, default `"Select a project to work with"`)
646
- * `options.noSelectTitle` **[String][128]** Dialog title when warning the user they need to select something (optional, default `'Select project'`)
647
- * `options.noSelectBody` **[String][128]** Dialog body when warning the user they need to select something (optional, default `'A project needs to be selected to continue'`)
662
+ * `options.autoSetActiveProject` **[Boolean][141]** After selecting a project set that project as active in TERA (optional, default `true`)
663
+ * `options.title` **[String][132]** The title of the dialog to display (optional, default `"Select a project to work with"`)
664
+ * `options.noSelectTitle` **[String][132]** Dialog title when warning the user they need to select something (optional, default `'Select project'`)
665
+ * `options.noSelectBody` **[String][132]** Dialog body when warning the user they need to select something (optional, default `'A project needs to be selected to continue'`)
648
666
 
649
- Returns **[Promise][135]<[Project][83]>** The active project
667
+ Returns **[Promise][139]<[Project][85]>** The active project
650
668
 
651
669
  ## selectProject
652
670
 
@@ -654,13 +672,13 @@ Prompt the user to select a project from those available
654
672
 
655
673
  ### Parameters
656
674
 
657
- * `options` **[Object][129]?** Additional options to mutate behaviour
675
+ * `options` **[Object][133]?** Additional options to mutate behaviour
658
676
 
659
- * `options.title` **[String][128]** The title of the dialog to display (optional, default `"Select a project to work with"`)
660
- * `options.allowCancel` **[Boolean][137]** Advertise cancelling the operation, the dialog can still be cancelled by closing it (optional, default `true`)
661
- * `options.setActive` **[Boolean][137]** Also set the project as active when selected (optional, default `false`)
677
+ * `options.title` **[String][132]** The title of the dialog to display (optional, default `"Select a project to work with"`)
678
+ * `options.allowCancel` **[Boolean][141]** Advertise cancelling the operation, the dialog can still be cancelled by closing it (optional, default `true`)
679
+ * `options.setActive` **[Boolean][141]** Also set the project as active when selected (optional, default `false`)
662
680
 
663
- Returns **[Promise][135]<[Project][83]>** The active project
681
+ Returns **[Promise][139]<[Project][85]>** The active project
664
682
 
665
683
  ## getProjectState
666
684
 
@@ -668,12 +686,12 @@ Return the current, full snapshot state of the active project
668
686
 
669
687
  ### Parameters
670
688
 
671
- * `options` **[Object][129]?** Additional options to mutate behaviour
689
+ * `options` **[Object][133]?** Additional options to mutate behaviour
672
690
 
673
- * `options.autoRequire` **[Boolean][137]** Run `requireProject()` automatically before continuing (optional, default `true`)
674
- * `Paths` **[Array][134]<[String][128]>** to subscribe to e.g. \['/users/'],
691
+ * `options.autoRequire` **[Boolean][141]** Run `requireProject()` automatically before continuing (optional, default `true`)
692
+ * `Paths` **[Array][138]<[String][132]>** to subscribe to e.g. \['/users/'],
675
693
 
676
- Returns **[Promise][135]<[Object][129]>** The current project state snapshot
694
+ Returns **[Promise][139]<[Object][133]>** The current project state snapshot
677
695
 
678
696
  ## setProjectState
679
697
 
@@ -685,13 +703,13 @@ Paths can be any valid Lodash.set() value such as:
685
703
 
686
704
  ### Parameters
687
705
 
688
- * `path` **([String][128] | [Array][134]<[String][128]>)** The sub-path within the project state to set
706
+ * `path` **([String][132] | [Array][138]<[String][132]>)** The sub-path within the project state to set
689
707
  * `value` **any** The value to set
690
- * `options` **[Object][129]?** Additional options to mutate behaviour
708
+ * `options` **[Object][133]?** Additional options to mutate behaviour
691
709
 
692
- * `options.save` **[Boolean][137]** Save the changes to the server immediately, disable to queue up multiple writes (optional, default `true`)
710
+ * `options.save` **[Boolean][141]** Save the changes to the server immediately, disable to queue up multiple writes (optional, default `true`)
693
711
 
694
- Returns **[Promise][135]** A promise which resolves when the operation has been dispatched to the server
712
+ Returns **[Promise][139]** A promise which resolves when the operation has been dispatched to the server
695
713
 
696
714
  ## setProjectStateDefaults
697
715
 
@@ -701,17 +719,31 @@ Set a nested value within the project state - just like `setProjectState()` - bu
701
719
 
702
720
  ### Parameters
703
721
 
704
- * `path` **([String][128] | [Array][134]<[String][128]>)** The sub-path within the project state to set
722
+ * `path` **([String][132] | [Array][138]<[String][132]>)** The sub-path within the project state to set
705
723
  * `value` **any** The value to set
706
- * `options` **[Object][129]?** Additional options to mutate behaviour, see setProjectState() for the full list of supported options
724
+ * `options` **[Object][133]?** Additional options to mutate behaviour, see setProjectState() for the full list of supported options
725
+
726
+ Returns **[Promise][139]<[Boolean][141]>** A promise which resolves to whether any changes were made - True if defaults were applied, false otherwise
727
+
728
+ ## setProjectStateFlush
707
729
 
708
- Returns **[Promise][135]<[Boolean][137]>** A promise which resolves to whether any changes were made - True if defaults were applied, false otherwise
730
+ Force copying local changes to the server
731
+ This is only ever needed when saving large quantities of data that need to be immediately available
732
+
733
+ Returns **[Promise][139]** A promise which resolves when the operation has completed
734
+
735
+ ## setProjectStateRefresh
736
+
737
+ Force refetching the remote project state into local
738
+ This is only ever needed when saving large quantities of data that need to be immediately available
739
+
740
+ Returns **[Promise][139]** A promise which resolves when the operation has completed
709
741
 
710
742
  ## saveProjectState
711
743
 
712
744
  Force-Save the currently active project state
713
745
 
714
- Returns **[Promise][135]** A promise which resolves when the operation has completed
746
+ Returns **[Promise][139]** A promise which resolves when the operation has completed
715
747
 
716
748
  ## replaceProjectState
717
749
 
@@ -722,9 +754,9 @@ You almost never want to use this function directly, see `setProjectState(path,
722
754
 
723
755
  ### Parameters
724
756
 
725
- * `newState` **[Object][129]** The new state to replace the current state with
757
+ * `newState` **[Object][133]** The new state to replace the current state with
726
758
 
727
- Returns **[Promise][135]** A promise which resolves when the operation has completed
759
+ Returns **[Promise][139]** A promise which resolves when the operation has completed
728
760
 
729
761
  ## applyProjectStatePatch
730
762
 
@@ -732,9 +764,9 @@ Apply a computed `just-diff` patch to the current project state
732
764
 
733
765
  ### Parameters
734
766
 
735
- * `Patch` **[Object][129]** to apply
767
+ * `Patch` **[Object][133]** to apply
736
768
 
737
- Returns **[Promise][135]** A promise which resolves when the operation has completed
769
+ Returns **[Promise][139]** A promise which resolves when the operation has completed
738
770
 
739
771
  ## subscribeProjectState
740
772
 
@@ -742,7 +774,7 @@ Subscribe to project state changes
742
774
  This will dispatch an RPC call to the source object `applyProjectStatePatchLocal()` function with the patch
743
775
  If the above call fails the subscriber is assumed as dead and unsubscribed from the polling list
744
776
 
745
- Returns **[Promise][135]<[Function][141]>** A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
777
+ Returns **[Promise][139]<[Function][145]>** A promise which resolves when a subscription has been created, call the resulting function to unsubscribe
746
778
 
747
779
  ## FileFilters
748
780
 
@@ -750,10 +782,10 @@ Data structure for a file filter
750
782
 
751
783
  ### Properties
752
784
 
753
- * `library` **[Boolean][137]?** Restrict to library files only
754
- * `filename` **[String][128]?** CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
755
- * `basename` **[String][128]?** CSV of @momsfriendlydevco/match expressions to filter the basename by
756
- * `ext` **[String][128]?** CSV of @momsfriendlydevco/match expressions to filter the file extension by
785
+ * `library` **[Boolean][141]?** Restrict to library files only
786
+ * `filename` **[String][132]?** CSV of @momsfriendlydevco/match expressions to filter the filename by (filenames are the basename sans extension)
787
+ * `basename` **[String][132]?** CSV of @momsfriendlydevco/match expressions to filter the basename by
788
+ * `ext` **[String][132]?** CSV of @momsfriendlydevco/match expressions to filter the file extension by
757
789
 
758
790
  ## selectProjectFile
759
791
 
@@ -761,20 +793,20 @@ Prompt the user to select a library to operate on
761
793
 
762
794
  ### Parameters
763
795
 
764
- * `options` **[Object][129]?** Additional options to mutate behaviour
796
+ * `options` **[Object][133]?** Additional options to mutate behaviour
765
797
 
766
- * `options.title` **[String][128]** The title of the dialog to display (optional, default `"Select a file"`)
767
- * `options.hint` **([String][128] | [Array][134]<[String][128]>)?** Hints to identify the file to select in array order of preference
768
- * `options.save` **[Boolean][137]** Set to truthy if saving a new file, UI will adjust to allowing overwrite OR new file name input (optional, default `false`)
769
- * `options.filters` **[FileFilters][104]?** Optional file filters
770
- * `options.allowUpload` **[Boolean][137]** Allow uploading new files (optional, default `true`)
771
- * `options.allowRefresh` **[Boolean][137]** Allow the user to manually refresh the file list (optional, default `true`)
772
- * `options.allowDownloadZip` **[Boolean][137]** Allow the user to download a Zip of all files (optional, default `true`)
773
- * `options.allowCancel` **[Boolean][137]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
774
- * `options.autoRequire` **[Boolean][137]** Run `requireProject()` automatically before continuing (optional, default `true`)
775
- * `options.filter` **[FileFilters][104]?** Optional file filters
798
+ * `options.title` **[String][132]** The title of the dialog to display (optional, default `"Select a file"`)
799
+ * `options.hint` **([String][132] | [Array][138]<[String][132]>)?** Hints to identify the file to select in array order of preference
800
+ * `options.save` **[Boolean][141]** Set to truthy if saving a new file, UI will adjust to allowing overwrite OR new file name input (optional, default `false`)
801
+ * `options.filters` **[FileFilters][108]?** Optional file filters
802
+ * `options.allowUpload` **[Boolean][141]** Allow uploading new files (optional, default `true`)
803
+ * `options.allowRefresh` **[Boolean][141]** Allow the user to manually refresh the file list (optional, default `true`)
804
+ * `options.allowDownloadZip` **[Boolean][141]** Allow the user to download a Zip of all files (optional, default `true`)
805
+ * `options.allowCancel` **[Boolean][141]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
806
+ * `options.autoRequire` **[Boolean][141]** Run `requireProject()` automatically before continuing (optional, default `true`)
807
+ * `options.filter` **[FileFilters][108]?** Optional file filters
776
808
 
777
- Returns **[Promise][135]<[ProjectFile][1]>** The eventually selected file
809
+ Returns **[Promise][139]<[ProjectFile][1]>** The eventually selected file
778
810
 
779
811
  ## setProjectFile
780
812
 
@@ -782,10 +814,10 @@ Replace a project files contents
782
814
 
783
815
  ### Parameters
784
816
 
785
- * `path` **[String][128]** File path to write
786
- * `contents` **(File | [Blob][132] | [FormData][133] | [Object][129] | [Array][134])** The new file contents
817
+ * `id` **[String][132]** File to overwrite
818
+ * `contents` **(File | [Blob][136] | [FormData][137] | [Object][133] | [Array][138])** The new file contents
787
819
 
788
- Returns **[Promise][135]** A promise which will resolve when the write operation has completed
820
+ Returns **[Promise][139]** A promise which will resolve when the write operation has completed
789
821
 
790
822
  ## selectProjectLibrary
791
823
 
@@ -793,18 +825,18 @@ Prompt the user to select a library to operate on and return a array of referenc
793
825
 
794
826
  ### Parameters
795
827
 
796
- * `options` **[Object][129]?** Additional options to mutate behaviour
828
+ * `options` **[Object][133]?** Additional options to mutate behaviour
797
829
 
798
- * `options.title` **[String][128]** The title of the dialog to display (optional, default `"Select a citation library"`)
799
- * `options.hint` **([String][128] | [Array][134]<[String][128]>)?** Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
800
- * `options.allowUpload` **[Boolean][137]** Allow uploading new files (optional, default `true`)
801
- * `options.allowRefresh` **[Boolean][137]** Allow the user to manually refresh the file list (optional, default `true`)
802
- * `options.allowDownloadZip` **[Boolean][137]** Allow the user to download a Zip of all files (optional, default `true`)
803
- * `options.allowCancel` **[Boolean][137]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
804
- * `options.autoRequire` **[Boolean][137]** Run `requireProject()` automatically before continuing (optional, default `true`)
805
- * `options.filters` **[FileFilters][104]?** Optional file filters, defaults to citation library selection only
830
+ * `options.title` **[String][132]** The title of the dialog to display (optional, default `"Select a citation library"`)
831
+ * `options.hint` **([String][132] | [Array][138]<[String][132]>)?** Hints to identify the library to select in array order of preference. Generally corresponds to the previous stage - e.g. 'deduped', 'review1', 'review2', 'dedisputed'
832
+ * `options.allowUpload` **[Boolean][141]** Allow uploading new files (optional, default `true`)
833
+ * `options.allowRefresh` **[Boolean][141]** Allow the user to manually refresh the file list (optional, default `true`)
834
+ * `options.allowDownloadZip` **[Boolean][141]** Allow the user to download a Zip of all files (optional, default `true`)
835
+ * `options.allowCancel` **[Boolean][141]** Allow cancelling the operation. Will throw `'CANCEL'` as the promise rejection if acationed (optional, default `true`)
836
+ * `options.autoRequire` **[Boolean][141]** Run `requireProject()` automatically before continuing (optional, default `true`)
837
+ * `options.filters` **[FileFilters][108]?** Optional file filters, defaults to citation library selection only
806
838
 
807
- Returns **[Promise][135]<[Array][134]\<Ref>>** A collection of references from the selected file
839
+ Returns **[Promise][139]<[Array][138]\<Ref>>** A collection of references from the selected file
808
840
 
809
841
  ## getProjectLibrary
810
842
 
@@ -812,15 +844,15 @@ Fetch + convert a project file into a library of citations
812
844
 
813
845
  ### Parameters
814
846
 
815
- * `path` **[String][128]** File path to read, if omitted the contents of `options` are used to guess at a suitable file
816
- * `options` **[Object][129]?** Additional options to mutate behaviour
847
+ * `id` **[String][132]** File ID to read
848
+ * `options` **[Object][133]?** Additional options to mutate behaviour
817
849
 
818
- * `options.format` **[String][128]** Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default `'json'`)
819
- * `options.autoRequire` **[Boolean][137]** Run `requireProject()` automatically before continuing (optional, default `true`)
820
- * `options.filter` **[Function][141]?** Optional async file filter, called each time as `(File:ProjectFile)`
821
- * `options.find` **[Function][141]?** Optional async final stage file filter to reduce all candidates down to one subject file
850
+ * `options.format` **[String][132]** Format for the file. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default `'json'`)
851
+ * `options.autoRequire` **[Boolean][141]** Run `requireProject()` automatically before continuing (optional, default `true`)
852
+ * `options.filter` **[Function][145]?** Optional async file filter, called each time as `(File:ProjectFile)`
853
+ * `options.find` **[Function][145]?** Optional async final stage file filter to reduce all candidates down to one subject file
822
854
 
823
- Returns **([Promise][135]<[Array][134]\<Ref>> | [Promise][135]\<any>)** A collection of references (default bevahiour) or a whatever format was requested
855
+ Returns **([Promise][139]<[Array][138]\<Ref>> | [Promise][139]\<any>)** A collection of references (default bevahiour) or a whatever format was requested
824
856
 
825
857
  ## setProjectLibrary
826
858
 
@@ -828,33 +860,33 @@ Save back a citation library from some input
828
860
 
829
861
  ### Parameters
830
862
 
831
- * `path` **[String][128]?** File path to save back to, if omitted one will be prompted for
832
- * `refs` **([Array][134]\<RefLibRef> | [Blob][132] | File)?** Collection of references for the selected library or the raw Blob/File
833
- * `options` **[Object][129]?** Additional options to mutate behaviour
863
+ * `id` **[String][132]?** File ID to save back to, if omitted a file will be prompted for
864
+ * `refs` **([Array][138]\<RefLibRef> | [Blob][136] | File)?** Collection of references for the selected library or the raw Blob/File
865
+ * `options` **[Object][133]?** Additional options to mutate behaviour
834
866
 
835
- * `options.path` **[String][128]?** Alternate method to specify the path to save as, if omitted one will be prompted for
836
- * `options.refs` **([Array][134]\<RefLibRef> | [Blob][132] | File)?** Alternate method to specify the refs to save as an array or raw Blob/File
837
- * `options.format` **[String][128]** Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default `'json'`)
838
- * `options.autoRequire` **[Boolean][137]** Run `requireProject()` automatically before continuing (optional, default `true`)
839
- * `options.hint` **[String][128]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
840
- * `options.filename` **[String][128]?** Suggested filename if path is unspecified
841
- * `options.title` **[String][128]** Dialog title if path is unspecified and we need to prompt (optional, default `'Save citation library'`)
842
- * `options.overwrite` **[Boolean][137]** Allow existing file upsert (optional, default `true`)
843
- * `options.meta` **[Object][129]?** Optional meta data to merge into the file data
867
+ * `options.id` **[String][132]?** Alternate method to specify the file ID to save as, if omitted one will be prompted for
868
+ * `options.refs` **([Array][138]\<RefLibRef> | [Blob][136] | File)?** Alternate method to specify the refs to save as an array or raw Blob/File
869
+ * `options.format` **[String][132]** Input format used. ENUM: 'pojo' (return a parsed JS collection), 'blob' (raw JS Blob object), 'file' (named JS File object) (optional, default `'json'`)
870
+ * `options.autoRequire` **[Boolean][141]** Run `requireProject()` automatically before continuing (optional, default `true`)
871
+ * `options.hint` **[String][132]?** Hint to store against the library. Generally corresponds to the current operation being performed - e.g. 'deduped'
872
+ * `options.filename` **[String][132]?** Suggested filename if `id` is unspecified
873
+ * `options.title` **[String][132]** Dialog title if `id` is unspecified and a prompt is necessary (optional, default `'Save citation library'`)
874
+ * `options.overwrite` **[Boolean][141]** Allow existing file upsert (optional, default `true`)
875
+ * `options.meta` **[Object][133]?** Optional meta data to merge into the file data
844
876
 
845
- Returns **[Promise][135]** A promise which resolves when the save operation has completed
877
+ Returns **[Promise][139]** A promise which resolves when the save operation has completed
846
878
 
847
879
  ## projectLog
848
880
 
849
881
  Create a log entry for the currently active project
850
882
 
851
- The required log object can be of various forms. See [https://tera-tools.com/api/logs.json][142] for the full list
883
+ The required log object can be of various forms. See [https://tera-tools.com/api/logs.json][146] for the full list
852
884
 
853
885
  ### Parameters
854
886
 
855
- * `log` **[Object][129]** The log entry to create
887
+ * `log` **[Object][133]** The log entry to create
856
888
 
857
- Returns **[Promise][135]** A promise which resolves when the operation has completed
889
+ Returns **[Promise][139]** A promise which resolves when the operation has completed
858
890
 
859
891
  ## setPageUrl
860
892
 
@@ -863,7 +895,7 @@ This only really makes a difference to tools within the tera-tools.com site wher
863
895
 
864
896
  ### Parameters
865
897
 
866
- * `url` **[String][128]** The URL to restore on next refresh
898
+ * `url` **[String][132]** The URL to restore on next refresh
867
899
 
868
900
  ## setPageTitle
869
901
 
@@ -872,7 +904,7 @@ This is usually called by a tool nested within the tera-tools.com embed
872
904
 
873
905
  ### Parameters
874
906
 
875
- * `title` **[String][128]** The current page title
907
+ * `title` **[String][132]** The current page title
876
908
 
877
909
  ## uiAlert
878
910
 
@@ -880,13 +912,13 @@ Display simple text within TERA
880
912
 
881
913
  ### Parameters
882
914
 
883
- * `text` **[String][128]** The text to display
884
- * `options` **[Object][129]?** Additional options to mutate behaviour
915
+ * `text` **[String][132]** The text to display
916
+ * `options` **[Object][133]?** Additional options to mutate behaviour
885
917
 
886
- * `options.title` **[String][128]** The title of the alert box (optional, default `'TERA'`)
887
- * `options.isHtml` **[Boolean][137]** If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default `false`)
918
+ * `options.title` **[String][132]** The title of the alert box (optional, default `'TERA'`)
919
+ * `options.isHtml` **[Boolean][141]** If falsy the text is rendered as plain-text otherwise it will be assumed as HTML content (optional, default `false`)
888
920
 
889
- Returns **[Promise][135]** A promise which resolves when the alert has been dismissed
921
+ Returns **[Promise][139]** A promise which resolves when the alert has been dismissed
890
922
 
891
923
  ## uiSplat
892
924
 
@@ -895,10 +927,10 @@ This function is ideally called within a requestFocus() wrapper
895
927
 
896
928
  ### Parameters
897
929
 
898
- * `content` **(DOMElement | [String][128] | `false`)** Either a prepared DOM element or string to compile, set to falsy to remove existing content
899
- * `options` **[Object][129]?** Additional options to mutate behaviour
930
+ * `content` **(DOMElement | [String][132] | `false`)** Either a prepared DOM element or string to compile, set to falsy to remove existing content
931
+ * `options` **[Object][133]?** Additional options to mutate behaviour
900
932
 
901
- * `options.logo` **([Boolean][137] | [String][128])** Add a logo to the output, if boolean true the Tera-tools logo is used otherwise specify a path or URL (optional, default `false`)
933
+ * `options.logo` **([Boolean][141] | [String][132])** Add a logo to the output, if boolean true the Tera-tools logo is used otherwise specify a path or URL (optional, default `false`)
902
934
 
903
935
  ## uiWindow
904
936
 
@@ -906,13 +938,13 @@ Open a popup window containing a new site
906
938
 
907
939
  ### Parameters
908
940
 
909
- * `url` **[String][128]** The URL to open
910
- * `options` **[Object][129]?** Additional options to mutate behaviour
941
+ * `url` **[String][132]** The URL to open
942
+ * `options` **[Object][133]?** Additional options to mutate behaviour
911
943
 
912
- * `options.width` **[Number][131]** The desired width of the window (optional, default `500`)
913
- * `options.height` **[Number][131]** The desired height of the window (optional, default `600`)
914
- * `options.center` **[Boolean][137]** Attempt to center the window on the screen (optional, default `true`)
915
- * `options.permissions` **[Object][129]?** Additional permissions to set on opening, defaults to a suitable set of permission for popups (see code)
944
+ * `options.width` **[Number][135]** The desired width of the window (optional, default `500`)
945
+ * `options.height` **[Number][135]** The desired height of the window (optional, default `600`)
946
+ * `options.center` **[Boolean][141]** Attempt to center the window on the screen (optional, default `true`)
947
+ * `options.permissions` **[Object][133]?** Additional permissions to set on opening, defaults to a suitable set of permission for popups (see code)
916
948
 
917
949
  Returns **WindowProxy** The opened window object (if `noopener` is not set in permissions)
918
950
 
@@ -926,276 +958,284 @@ Returns **WindowProxy** The opened window object (if `noopener` is not set in pe
926
958
 
927
959
  [5]: #path
928
960
 
929
- [6]: #parsedname
961
+ [6]: #url
962
+
963
+ [7]: #teraurl
964
+
965
+ [8]: #parsedname
966
+
967
+ [9]: #properties
968
+
969
+ [10]: #created
930
970
 
931
- [7]: #properties
971
+ [11]: #createdformatted
932
972
 
933
- [8]: #created
973
+ [12]: #modified
934
974
 
935
- [9]: #createdformatted
975
+ [13]: #modifiedformatted
936
976
 
937
- [10]: #modified
977
+ [14]: #accessed
938
978
 
939
- [11]: #modifiedformatted
979
+ [15]: #accessedformatted
940
980
 
941
- [12]: #accessed
981
+ [16]: #size
942
982
 
943
- [13]: #accessedformatted
983
+ [17]: #sizeformatted
944
984
 
945
- [14]: #size
985
+ [18]: #mime
946
986
 
947
- [15]: #sizeformatted
987
+ [19]: #meta
948
988
 
949
- [16]: #mime
989
+ [20]: #getcontents
950
990
 
951
- [17]: #meta
991
+ [21]: #setcontents
952
992
 
953
- [18]: #getcontents
993
+ [22]: #parameters
954
994
 
955
- [19]: #setcontents
995
+ [23]: #getrefs
956
996
 
957
- [20]: #parameters
997
+ [24]: #setrefs
958
998
 
959
- [21]: #getrefs
999
+ [25]: #parameters-1
960
1000
 
961
- [22]: #setrefs
1001
+ [26]: #serialize
962
1002
 
963
- [23]: #parameters-1
1003
+ [27]: #deserialize
964
1004
 
965
- [24]: #serialize
1005
+ [28]: #parameters-2
966
1006
 
967
- [25]: #deserialize
1007
+ [29]: #tera
968
1008
 
969
- [26]: #parameters-2
1009
+ [30]: #parameters-3
970
1010
 
971
- [27]: #tera
1011
+ [31]: #terafy
972
1012
 
973
- [28]: #parameters-3
1013
+ [32]: #settings
974
1014
 
975
- [29]: #terafy
1015
+ [33]: #properties-1
976
1016
 
977
- [30]: #settings
1017
+ [34]: #events
978
1018
 
979
- [31]: #properties-1
1019
+ [35]: #dom
980
1020
 
981
- [32]: #events
1021
+ [36]: #properties-2
982
1022
 
983
- [33]: #dom
1023
+ [37]: #methods
984
1024
 
985
- [34]: #properties-2
1025
+ [38]: #plugins
986
1026
 
987
- [35]: #methods
1027
+ [39]: #send
988
1028
 
989
- [36]: #plugins
1029
+ [40]: #parameters-4
990
1030
 
991
- [37]: #send
1031
+ [41]: #sendraw
992
1032
 
993
- [38]: #parameters-4
1033
+ [42]: #parameters-5
994
1034
 
995
- [39]: #sendraw
1035
+ [43]: #rpc
996
1036
 
997
- [40]: #parameters-5
1037
+ [44]: #parameters-6
998
1038
 
999
- [41]: #rpc
1039
+ [45]: #acceptmessage
1000
1040
 
1001
- [42]: #parameters-6
1041
+ [46]: #parameters-7
1002
1042
 
1003
- [43]: #acceptmessage
1043
+ [47]: #acceptpostboxes
1004
1044
 
1005
- [44]: #parameters-7
1045
+ [48]: #createprojectstatepatch
1006
1046
 
1007
- [45]: #acceptpostboxes
1047
+ [49]: #parameters-8
1008
1048
 
1009
- [46]: #createprojectstatepatch
1049
+ [50]: #applyprojectstatepatchlocal
1010
1050
 
1011
- [47]: #parameters-8
1051
+ [51]: #parameters-9
1012
1052
 
1013
- [48]: #applyprojectstatepatchlocal
1053
+ [52]: #init
1014
1054
 
1015
- [49]: #parameters-9
1055
+ [53]: #parameters-10
1016
1056
 
1017
- [50]: #init
1057
+ [54]: #detectmode
1018
1058
 
1019
- [51]: #parameters-10
1059
+ [55]: #injectcomms
1020
1060
 
1021
- [52]: #detectmode
1061
+ [56]: #injectstylesheet
1022
1062
 
1023
- [53]: #injectcomms
1063
+ [57]: #injectmethods
1024
1064
 
1025
- [54]: #injectstylesheet
1065
+ [58]: #debug
1026
1066
 
1027
- [55]: #injectmethods
1067
+ [59]: #parameters-11
1028
1068
 
1029
- [56]: #debug
1069
+ [60]: #set
1030
1070
 
1031
- [57]: #parameters-11
1071
+ [61]: #parameters-12
1032
1072
 
1033
- [58]: #set
1073
+ [62]: #setifdev
1034
1074
 
1035
- [59]: #parameters-12
1075
+ [63]: #parameters-13
1036
1076
 
1037
- [60]: #setifdev
1077
+ [64]: #use
1038
1078
 
1039
- [61]: #parameters-13
1079
+ [65]: #parameters-14
1040
1080
 
1041
- [62]: #use
1081
+ [66]: #mixin
1042
1082
 
1043
- [63]: #parameters-14
1083
+ [67]: #parameters-15
1044
1084
 
1045
- [64]: #mixin
1085
+ [68]: #toggledevmode
1046
1086
 
1047
- [65]: #parameters-15
1087
+ [69]: #parameters-16
1048
1088
 
1049
- [66]: #toggledevmode
1089
+ [70]: #togglefocus
1050
1090
 
1051
- [67]: #parameters-16
1091
+ [71]: #parameters-17
1052
1092
 
1053
- [68]: #togglefocus
1093
+ [72]: #selectprojectfile
1054
1094
 
1055
- [69]: #parameters-17
1095
+ [73]: #parameters-18
1056
1096
 
1057
- [70]: #selectprojectfile
1097
+ [74]: #getprojectfiles
1058
1098
 
1059
- [71]: #parameters-18
1099
+ [75]: #parameters-19
1060
1100
 
1061
- [72]: #getprojectfiles
1101
+ [76]: #getprojectfile
1062
1102
 
1063
- [73]: #parameters-19
1103
+ [77]: #parameters-20
1064
1104
 
1065
- [74]: #getprojectfile
1105
+ [78]: #handshake
1066
1106
 
1067
- [75]: #parameters-20
1107
+ [79]: #properties-3
1068
1108
 
1069
- [76]: #handshake
1109
+ [80]: #user
1070
1110
 
1071
- [77]: #properties-3
1111
+ [81]: #properties-4
1072
1112
 
1073
- [78]: #user
1113
+ [82]: #getuser
1074
1114
 
1075
- [79]: #properties-4
1115
+ [83]: #requireuser
1076
1116
 
1077
- [80]: #getuser
1117
+ [84]: #parameters-21
1078
1118
 
1079
- [81]: #requireuser
1119
+ [85]: #project
1080
1120
 
1081
- [82]: #parameters-21
1121
+ [86]: #getproject
1082
1122
 
1083
- [83]: #project
1123
+ [87]: #getprojects
1084
1124
 
1085
- [84]: #getproject
1125
+ [88]: #setactiveproject
1086
1126
 
1087
- [85]: #getprojects
1127
+ [89]: #parameters-22
1088
1128
 
1089
- [86]: #setactiveproject
1129
+ [90]: #requireproject
1090
1130
 
1091
- [87]: #parameters-22
1131
+ [91]: #parameters-23
1092
1132
 
1093
- [88]: #requireproject
1133
+ [92]: #selectproject
1094
1134
 
1095
- [89]: #parameters-23
1135
+ [93]: #parameters-24
1096
1136
 
1097
- [90]: #selectproject
1137
+ [94]: #getprojectstate
1098
1138
 
1099
- [91]: #parameters-24
1139
+ [95]: #parameters-25
1100
1140
 
1101
- [92]: #getprojectstate
1141
+ [96]: #setprojectstate
1102
1142
 
1103
- [93]: #parameters-25
1143
+ [97]: #parameters-26
1104
1144
 
1105
- [94]: #setprojectstate
1145
+ [98]: #setprojectstatedefaults
1106
1146
 
1107
- [95]: #parameters-26
1147
+ [99]: #parameters-27
1108
1148
 
1109
- [96]: #setprojectstatedefaults
1149
+ [100]: #setprojectstateflush
1110
1150
 
1111
- [97]: #parameters-27
1151
+ [101]: #setprojectstaterefresh
1112
1152
 
1113
- [98]: #saveprojectstate
1153
+ [102]: #saveprojectstate
1114
1154
 
1115
- [99]: #replaceprojectstate
1155
+ [103]: #replaceprojectstate
1116
1156
 
1117
- [100]: #parameters-28
1157
+ [104]: #parameters-28
1118
1158
 
1119
- [101]: #applyprojectstatepatch
1159
+ [105]: #applyprojectstatepatch
1120
1160
 
1121
- [102]: #parameters-29
1161
+ [106]: #parameters-29
1122
1162
 
1123
- [103]: #subscribeprojectstate
1163
+ [107]: #subscribeprojectstate
1124
1164
 
1125
- [104]: #filefilters
1165
+ [108]: #filefilters
1126
1166
 
1127
- [105]: #properties-5
1167
+ [109]: #properties-5
1128
1168
 
1129
- [106]: #selectprojectfile-1
1169
+ [110]: #selectprojectfile-1
1130
1170
 
1131
- [107]: #parameters-30
1171
+ [111]: #parameters-30
1132
1172
 
1133
- [108]: #setprojectfile
1173
+ [112]: #setprojectfile
1134
1174
 
1135
- [109]: #parameters-31
1175
+ [113]: #parameters-31
1136
1176
 
1137
- [110]: #selectprojectlibrary
1177
+ [114]: #selectprojectlibrary
1138
1178
 
1139
- [111]: #parameters-32
1179
+ [115]: #parameters-32
1140
1180
 
1141
- [112]: #getprojectlibrary
1181
+ [116]: #getprojectlibrary
1142
1182
 
1143
- [113]: #parameters-33
1183
+ [117]: #parameters-33
1144
1184
 
1145
- [114]: #setprojectlibrary
1185
+ [118]: #setprojectlibrary
1146
1186
 
1147
- [115]: #parameters-34
1187
+ [119]: #parameters-34
1148
1188
 
1149
- [116]: #projectlog
1189
+ [120]: #projectlog
1150
1190
 
1151
- [117]: #parameters-35
1191
+ [121]: #parameters-35
1152
1192
 
1153
- [118]: #setpageurl
1193
+ [122]: #setpageurl
1154
1194
 
1155
- [119]: #parameters-36
1195
+ [123]: #parameters-36
1156
1196
 
1157
- [120]: #setpagetitle
1197
+ [124]: #setpagetitle
1158
1198
 
1159
- [121]: #parameters-37
1199
+ [125]: #parameters-37
1160
1200
 
1161
- [122]: #uialert
1201
+ [126]: #uialert
1162
1202
 
1163
- [123]: #parameters-38
1203
+ [127]: #parameters-38
1164
1204
 
1165
- [124]: #uisplat
1205
+ [128]: #uisplat
1166
1206
 
1167
- [125]: #parameters-39
1207
+ [129]: #parameters-39
1168
1208
 
1169
- [126]: #uiwindow
1209
+ [130]: #uiwindow
1170
1210
 
1171
- [127]: #parameters-40
1211
+ [131]: #parameters-40
1172
1212
 
1173
- [128]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
1213
+ [132]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
1174
1214
 
1175
- [129]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
1215
+ [133]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
1176
1216
 
1177
- [130]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
1217
+ [134]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date
1178
1218
 
1179
- [131]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
1219
+ [135]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
1180
1220
 
1181
- [132]: https://developer.mozilla.org/docs/Web/API/Blob
1221
+ [136]: https://developer.mozilla.org/docs/Web/API/Blob
1182
1222
 
1183
- [133]: https://developer.mozilla.org/docs/Web/API/FormData
1223
+ [137]: https://developer.mozilla.org/docs/Web/API/FormData
1184
1224
 
1185
- [134]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
1225
+ [138]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
1186
1226
 
1187
- [135]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
1227
+ [139]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
1188
1228
 
1189
- [136]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
1229
+ [140]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
1190
1230
 
1191
- [137]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
1231
+ [141]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
1192
1232
 
1193
- [138]: https://developer.mozilla.org/docs/Web/API/Window
1233
+ [142]: https://developer.mozilla.org/docs/Web/API/Window
1194
1234
 
1195
- [139]: https://developer.mozilla.org/docs/Web/API/MessageEvent
1235
+ [143]: https://developer.mozilla.org/docs/Web/API/MessageEvent
1196
1236
 
1197
- [140]: http://jsonpatch.com
1237
+ [144]: http://jsonpatch.com
1198
1238
 
1199
- [141]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
1239
+ [145]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
1200
1240
 
1201
- [142]: https://tera-tools.com/api/logs.json
1241
+ [146]: https://tera-tools.com/api/logs.json