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