@runic-artifex/vue 0.15.1 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -196,13 +196,34 @@ is written. A string set on `value` of a field that is not text is taken as its
196
196
  `errors` holds the member's validation messages from the descriptor (`[]` when valid), `error` why the latest write
197
197
  or text failed (a `BridgeError` or a `FieldError`, whose `kind` is `rejected`, `conflict`, `committed-with-error` or
198
198
  `invalid-text`). `FieldError`, `FieldOptions`, `FieldState` and `BridgeField` are exported from this package. See the
199
- [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#fields) for the receipts
200
- and text forms.
199
+ [field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#fields) for the receipts
200
+ and text forms. An `invalid-text` error has a `reason` and `arguments`: render `useText(() => title.error)` after
201
+ `configureFieldErrorText` to show your own text for it in the window's language
202
+ ([Translating field errors](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#translating-field-errors)).
203
+
204
+ #### Row cells and nested members
205
+
206
+ Since 0.16, `InvoiceFields.address.street` and `InvoiceFields.lines.at(line.id).quantity` are fields too
207
+ (`field-paths/1`): a member of an object member, and a cell of a row that .NET edits with `[RunicRowEditor]`. Call
208
+ `useField` in the row's component (`v-model="quantity.text"`); `at(key)` returns the same descriptor for the same
209
+ key. Such a field always writes checked, conflicts only when another writer changed the same cell, and shows the
210
+ messages .NET reports at the cell's validation path. See
211
+ [Fields below a member and row cells](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/vue/../views/README.md#fields-below-a-member-and-row-cells).
212
+
213
+ ### Forms: `useForm(fields, options?)`
214
+
215
+ One `reactive` state over field handles, and a `submit` that writes every field before its command
216
+ (`createFormController` in `@runic-artifex/views`). `dirty` counts drafts not written yet and the `dirty` option.
217
+
218
+ ```vue
219
+ const form = useForm({ title, step }, { dirty: () => editor.state.value?.isDirty === true });
220
+ <button :disabled="!form.valid || form.submitting" @click="form.submit(() => editor.client.value!.save())">Save</button>
221
+ ```
201
222
 
202
223
  ### Text inputs: `useTextField(view, read, write, options?)`
203
224
 
204
225
  Binds a text input to a member through the framework-neutral
205
- [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#text-inputs)
226
+ [text field controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#text-inputs)
206
227
  while the effect scope is active. Each field is a ref, so the handle can be destructured:
207
228
 
208
229
  ```vue
@@ -245,8 +266,11 @@ text at once and hides the race.
245
266
 
246
267
  Renders the component registered for a generated reference's `kind` and
247
268
  passes the reference as its `page` prop. A different reference remounts the
248
- component, a kind without a component renders an English `<p role="alert">`
249
- (or the `missing` slot), and the default slot renders while `content` is empty:
269
+ component, a kind without a component renders the `missing` slot, and the
270
+ default slot renders while `content` is empty. Without the slot, a development
271
+ build (`process.env.NODE_ENV` is not `production`) renders an English
272
+ `<p role="alert">`; a production build renders nothing and reports the kind once
273
+ through the page's error reporting (`installErrorReporting`, `onBridgeDiagnostic`):
250
274
 
251
275
  ```vue
252
276
  <script setup lang="ts">
@@ -265,7 +289,11 @@ const { state } = useView({ connect: connectWorkspace });
265
289
  ```
266
290
 
267
291
  `satisfies ViewRegistry<…>` checks that every kind has a component whose `page`
268
- prop accepts that reference.
292
+ prop accepts that reference. A component whose `page` is a shared page
293
+ reference, such as `ResultPagePageReference` of a .NET
294
+ [`[RunicSharedClient]`](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/vue/../../dotnet/Runic.Application.Views/README.md#shared-clients)
295
+ interface, registers for each of its kinds:
296
+ `{ ...registryEntries(resultPageKinds, ResultPage), settings: Settings }`.
269
297
 
270
298
  The `missing` slot replaces the English alert, for example with localized text.
271
299
  It receives `{ content }`, the reference whose kind has no component, and its
@@ -277,6 +305,70 @@ markup (including any `role`) is yours:
277
305
  </ViewOutlet>
278
306
  ```
279
307
 
308
+ ### Region collections
309
+
310
+ A .NET `[RunicRegionCollection]` member, such as `state.documents`, lists
311
+ regions that each keep their own back stack. `<RegionOutlets>` renders a
312
+ `ViewOutlet` for each region, keyed by the region's key, inside a
313
+ `<div data-region-key>`. The default `mode="keep-mounted"` keeps every region mounted
314
+ and sets `hidden` and an inline `display: none` on all but the selected one, so
315
+ a tab keeps its component, scroll position and unsent input. Author CSS cannot
316
+ show a hidden panel without `!important`. `mode="selected"` renders only the
317
+ selected region. The default slot renders while there is no region, and the
318
+ `missing` slot is passed to each outlet. A region with `content: null` renders
319
+ nothing.
320
+
321
+ The package has no tab bar. Build one with `regionEntries` and the generated
322
+ `selectDocuments(key)` and `closeDocuments(key)`. The `panelProps(entry)` prop returns attributes for each region's wrapper,
323
+ such as `id`, `role="tabpanel"` and `aria-labelledby`, so each tab can name its
324
+ panel in `aria-controls`. `hidden` and `data-region-key` stay controlled by the
325
+ outlet, and a returned `style` is merged with its `display: none`.
326
+
327
+ ```vue
328
+ <script setup lang="ts">
329
+ const tabId = (key: string) => `document-tab-${key}`;
330
+ const panelId = (key: string) => `document-panel-${key}`;
331
+ async function close(key: string) {
332
+ if ((await client.value?.closeDocuments(key))?.kind !== "Committed") return;
333
+ await nextTick();
334
+ const selected = selectedRegion(state.value?.documents);
335
+ if (selected) document.getElementById(tabId(selected.key))?.focus();
336
+ }
337
+ </script>
338
+
339
+ <template>
340
+ <div role="tablist">
341
+ <span v-for="tab in regionEntries(state?.documents)" :key="tab.key">
342
+ <button :id="tabId(tab.key)" role="tab" :aria-selected="tab.selected" :aria-controls="panelId(tab.key)"
343
+ @click="client?.selectDocuments(tab.key)">
344
+ {{ tab.content?.kind ?? "Empty" }}
345
+ </button>
346
+ <button aria-label="Close" @click="close(tab.key)">×</button>
347
+ </span>
348
+ </div>
349
+ <RegionOutlets :collection="state?.documents" :registry="documentPages"
350
+ :panel-props="tab => ({ id: panelId(tab.key), role: 'tabpanel', 'aria-labelledby': tabId(tab.key) })">
351
+ <p>No open documents</p>
352
+ </RegionOutlets>
353
+ </template>
354
+ ```
355
+
356
+ `selected` changes only when a switch or close commits. A departure guard can
357
+ keep the current tab, so highlight `selected` and do not move the highlight
358
+ before the request settles. `select…` and `close…` resolve to the .NET
359
+ `NavigationOutcome`, such as `{ kind: "Rejected", rejection: "Guard" }`.
360
+
361
+ Closing the selected tab removes its button, and the next tab becomes selected
362
+ when the close commits. After `closeDocuments` resolves with `kind: "Committed"`,
363
+ move focus to the button of the new selected tab, as `close` above does.
364
+
365
+ In both modes the region collection keeps presenting every region's content,
366
+ so the pages of hidden tabs stay live and still receive state. `"selected"`
367
+ mode only unmounts the components of the regions that are not selected.
368
+
369
+ `regionEntries`, `selectedRegion` and the region types are re-exported from
370
+ `@runic-artifex/views`.
371
+
280
372
  ## `useCommand(command)`
281
373
 
282
374
  Returns `{ run, pending, error, failure, reset }`, with `pending`, `error` and
@@ -304,7 +396,7 @@ neither.
304
396
  ## `useOperation(start, options?)`
305
397
 
306
398
  Observes a generated `start<Command>()` operation through the framework-neutral
307
- [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#operation-feedback-and-latest-selection)
399
+ [operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#operation-feedback-and-latest-selection)
308
400
  and returns each state field as a shallow ref, with `run`, `cancel` and `reset`:
309
401
 
310
402
  ```vue
@@ -336,7 +428,7 @@ Disposing the effect scope settles run promises without cancelling accepted work
336
428
 
337
429
  Admits only the newest of several reads, for example loading the item the user
338
430
  selected last, through the framework-neutral
339
- [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#operation-feedback-and-latest-selection),
431
+ [latest-operation controller](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#operation-feedback-and-latest-selection),
340
432
  and returns each state field as a shallow ref, with `run` and `clear`. Each
341
433
  `run(intent)` replaces the queued intent and cancels the active read; the next read
342
434
  starts only after the previous one reaches its terminal status and the intent's
@@ -373,7 +465,7 @@ from `@runic-artifex/views` (re-exported here since 0.11, with the
373
465
  `BridgeConnectionState` and `BridgeConnectionOptions` types) and returns `{ state }`, a shallow ref holding a
374
466
  `BridgeConnectionState`: `connecting`, `connected`, `reconnecting`, `lost` or `closed` (the
375
467
  application closed the window, since 0.15; a closed set, see
376
- [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#connection-state)):
468
+ [Connection state](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#connection-state)):
377
469
 
378
470
  ```vue
379
471
  <script setup lang="ts">
@@ -396,7 +488,7 @@ development builds warn. An invalid `lostAfter` throws a `RangeError`.
396
488
  Follows the declared menu bar of a Runic Desktop window that leaves it to the
397
489
  page (`DesktopMenuBarPresentation.Page`) until the current effect scope is
398
490
  disposed. It wraps `createMenuBarController` from `@runic-artifex/views` (see
399
- [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a shallow ref
491
+ [In-page menu bar](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#in-page-menu-bar)) and returns `{ state, invoke, handleKeyDown }`: `state` is a shallow ref
400
492
  of a `MenuBarState`, and the bar is rendered by the menubar component of the
401
493
  application's own UI library. Runic ships no menubar component.
402
494
 
@@ -427,7 +519,7 @@ rendering creates no controller: `state` stays `connecting`.
427
519
  ### With Reka UI
428
520
 
429
521
  Reka UI's `MenubarRoot` with `v-model` of the open menu; the
430
- [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
522
+ [Notes example](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/examples/notes-view-first#in-page-menu-bar) adds submenus, check and radio
431
523
  items and is tested with real keys:
432
524
 
433
525
  ```vue
@@ -472,6 +564,47 @@ const { state: menuBar, invoke } = useMenuBar({
472
564
  </template>
473
565
  ```
474
566
 
567
+ ## `useText(value, fallback?)`
568
+
569
+ Shows a text reference that a ViewModel produced, such as a status line or a
570
+ validation error's `text`, in the window's language, and renders again when the
571
+ language changes. A string shows as it is; `null` and `undefined` show
572
+ `fallback`. Connect the page's Translations runtime once with
573
+ `configureTranslatedText` ([Translated text](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/dotnet/Runic.Application.Views/README.md#translated-text)).
574
+ `useWindowLocale()` reads the window's locale.
575
+
576
+ `useTextLocale()` is the locale that text is shown in, as a ref. It is one ref
577
+ for the page and needs no effect scope, so the locale resolver can read it;
578
+ templates that call `m.*()` then render again on a language switch.
579
+ `syncDocumentLocale()` keeps `<html lang dir>` on that locale:
580
+
581
+ ```ts
582
+ // main.ts
583
+ const textLocale = useTextLocale();
584
+ configureLocaleResolver(() => textLocale.value ?? locale.getLocale());
585
+ configureTranslatedText({ ...locale, resolve, direction: localeDirection });
586
+ syncDocumentLocale();
587
+ ```
588
+
589
+ ```ts
590
+ const status = useText(() => view.state.value?.status);
591
+ // <p>{{ status }}</p>
592
+ ```
593
+
594
+ ## `useAppearance()`
595
+
596
+ The page's appearance as a ref that renders, computes and watches again when it
597
+ changes, while the calling component or effect scope lives: the colour scheme,
598
+ contrast and reduced motion of the page's engine, combined with the desktop's
599
+ text scale, accent colour, forced-colours palette, contrast and motion that a
600
+ Runic host pushes ([Appearance](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/views/README.md#appearance)). Every member is `null` under
601
+ server rendering.
602
+
603
+ ```ts
604
+ const look = useAppearance();
605
+ const fontSize = computed(() => `${look.value.textScale ?? 1}rem`);
606
+ ```
607
+
475
608
  ## Errors
476
609
 
477
610
  The `error` of `useView` and of a command or operation handle is typed
@@ -489,7 +622,7 @@ const message = computed(() => describeBridgeError(error.value));
489
622
  ```
490
623
 
491
624
  `instanceof` holds for errors from every copy of the package on the page.
492
- [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#errors-and-diagnostics)
625
+ [Errors and diagnostics](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#errors-and-diagnostics)
493
626
  lists the kinds. Any other value, such as an exception that your own connect
494
627
  function or command callback throws, arrives unchanged.
495
628
 
@@ -536,15 +669,53 @@ application's own dialog.
536
669
  departure before that is answered by the ViewModel's .NET fallback handler, or
537
670
  fails closed without one.
538
671
 
539
- The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.15.1/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
672
+ The [ReactiveUI leave confirmation](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/dotnet/Runic.Application.Views.ReactiveUI/README.md#leave-confirmation-in-a-web-view)
540
673
  has the .NET side and which View answers which departure. In a frontend test,
541
674
  the generated mock's `interactions.<name>.request(input)` resolves with the
542
- registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#testing).
675
+ registered handler's answer; see the [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#testing).
676
+
677
+ ## View requests
678
+
679
+ A `ViewRequest<T>` property of the ViewModel asks the View for a one-way
680
+ presentation action, such as focusing a field or showing a toast, and is
681
+ `client.requests.<name>` on the generated client. Register the page's
682
+ handler in `watchEffect`: `handle((input, { signal }) => …)` returns the function
683
+ that removes it, so pass that to `onCleanup`, and Vue removes the handler when
684
+ the client changes or the component unmounts:
685
+
686
+ ```vue
687
+ <script setup lang="ts">
688
+ import { useTemplateRef, watchEffect } from "vue";
689
+ import { useView } from "@runic-artifex/vue";
690
+ import type { EditPageReference } from "./generated/edit.js";
691
+
692
+ const props = defineProps<{ page: EditPageReference }>();
693
+ const { client } = useView(() => props.page);
694
+ const name = useTemplateRef<HTMLInputElement>("name");
695
+ watchEffect(onCleanup => {
696
+ const remove = client.value?.requests.focus.handle(({ member }) => {
697
+ if (member === "name") name.value?.focus();
698
+ });
699
+ if (remove) onCleanup(remove);
700
+ });
701
+ </script>
702
+
703
+ <template><input ref="name"></template>
704
+ ```
705
+
706
+ `input` is typed from the request's `ViewRequest<T>`. The handler runs once
707
+ the page painted the state the request was raised with, so the field of that
708
+ state is rendered; `signal` aborts when the handler is replaced or removed, the
709
+ client is disposed or the connection is lost. A request is never replayed: one
710
+ raised before the effect ran, or while the page is disconnected, is not
711
+ delivered later. See [View requests](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#view-requests) for the rules, and in a frontend
712
+ test raise one with the generated mock's `requests.<name>.raise(input)` (the
713
+ [Testing guide](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#testing)).
543
714
 
544
715
  ## `useCollectionViewport(options)`
545
716
 
546
717
  Follows a fixed-row-height scroll container and returns `{ viewport, attach }`.
547
- `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/views#collectionviewportoptions)
718
+ `viewport` is a shallow ref with the [`collectionViewport`](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#collectionviewportoptions)
548
719
  range; `attach` is a function ref for the container. Bind it to a native element
549
720
  such as a `<div>`: a component instance (`:ref="attach"` on a component) or a
550
721
  non-HTML element detaches the viewport, and development builds warn. Pass a getter for the
@@ -565,3 +736,34 @@ watch(() => [viewport.value.start, viewport.value.size] as const, ([start, size]
565
736
  </div>
566
737
  </template>
567
738
  ```
739
+
740
+ ## `useQueryCollection(collection, options)`
741
+
742
+ Follows a scroll container for a [query collection](https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/views#query-collections) (`client.queries.{name}`), whose rows stay in .NET: it
743
+ loads the rows the container shows, with placeholders until they arrive, and lays them out with variable heights.
744
+ Pass the collection or a getter (`() => client.value?.queries.rows`) and the options. `viewport` is a ref of the
745
+ `QueryViewport` (`items` with `top` and `size`, `totalSize`, `total`, `query`, `loading`, `error`); bind `attach` to the
746
+ container and `measure` to each row, and call `scrollToKey`, `scrollToIndex`, `setQuery` or `retry`:
747
+
748
+ ```vue
749
+ <script setup lang="ts">
750
+ const list = useQueryCollection(() => client.value?.queries.rows, { estimateSize: 32 });
751
+ </script>
752
+ <template>
753
+ <div :ref="list.attach" style="height: 480px; overflow: auto">
754
+ <div :style="{ height: `${list.viewport.value.totalSize}px`, position: 'relative' }">
755
+ <div v-for="item in list.viewport.value.items" :key="item.key ?? `p${item.index}`" :ref="el => list.measure(el, item.index)"
756
+ :style="{ position: 'absolute', top: `${item.top}px`, width: '100%' }">{{ item.row?.label ?? "…" }}</div>
757
+ </div>
758
+ </div>
759
+ </template>
760
+ ```
761
+
762
+ ## Back and the URL
763
+
764
+ The package re-exports `installBackNavigation`, `installNavigationPath`,
765
+ `navigateBack`, `openNavigationPath` and `onNavigationPath` from
766
+ `@runic-artifex/views` (since 0.16). Call the installs once where the page
767
+ starts, before or after mounting: the mouse's Back button and Alt+Left then go
768
+ back in the .NET window, and `#/customers/42` follows its path region. See
769
+ [Back and the URL](https://github.com/Runic-Artifex/runic-sdk/blob/v0.17.0/packages/web/views/README.md#back-and-the-url).
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Whether the page is a development build. A page whose bundler does not replace NODE_ENV, such as Vue's esm-browser
3
+ * build through an import map, counts as production instead of throwing `process is not defined`.
4
+ */
5
+ export declare function isDevelopment(): boolean;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Whether the page is a development build. A page whose bundler does not replace NODE_ENV, such as Vue's esm-browser
3
+ * build through an import map, counts as production instead of throwing `process is not defined`.
4
+ */
5
+ export function isDevelopment() {
6
+ try {
7
+ return process.env.NODE_ENV !== "production";
8
+ }
9
+ catch {
10
+ return false;
11
+ }
12
+ }
package/dist/form.d.ts ADDED
@@ -0,0 +1,27 @@
1
+ import { type MaybeRefOrGetter } from "vue";
2
+ import { type FieldState, type FormField, type FormFields, type FormState, type FormSubmitOptions, type FormSubmitResult } from "@runic-artifex/views";
3
+ /** A field as {@link useForm} reads it: a `useField` handle. */
4
+ export type FormFieldHandle = FormField & Pick<FieldState<unknown>, "editing" | "validating" | "errors" | "error">;
5
+ export interface UseFormOptions {
6
+ /** Whether the View reports unsaved changes, such as `() => editor.state.value?.isDirty === true`. */
7
+ readonly dirty?: MaybeRefOrGetter<boolean | undefined>;
8
+ }
9
+ /** A form bound by {@link useForm}: a `reactive` state and its actions. */
10
+ export interface FormHandle extends FormState {
11
+ /** Commits every field, waits for their writes and runs `command` unless a field's write or text failed. */
12
+ submit<T>(command: () => T | PromiseLike<T>, options?: FormSubmitOptions): Promise<FormSubmitResult<T>>;
13
+ /** Commits every field and resolves once their writes settled. */
14
+ commit(): Promise<FormState>;
15
+ /** Resets every field. */
16
+ reset(): void;
17
+ }
18
+ /**
19
+ * One dirty, pending and valid state over `useField` handles, and a `submit` that writes every field before its
20
+ * command (`createFormController` in `@runic-artifex/views`):
21
+ *
22
+ * ```vue
23
+ * const form = useForm({ title, body }, { dirty: () => editor.state.value?.isDirty === true });
24
+ * <button :disabled="!form.valid || form.submitting" @click="form.submit(() => editor.client.value!.save())">Save</button>
25
+ * ```
26
+ */
27
+ export declare function useForm(fields: FormFields<FormFieldHandle>, options?: UseFormOptions): FormHandle;
package/dist/form.js ADDED
@@ -0,0 +1,41 @@
1
+ import { computed, reactive, shallowRef, toValue } from "vue";
2
+ import { formFieldList, formStateOf, submitFields, } from "@runic-artifex/views";
3
+ /**
4
+ * One dirty, pending and valid state over `useField` handles, and a `submit` that writes every field before its
5
+ * command (`createFormController` in `@runic-artifex/views`):
6
+ *
7
+ * ```vue
8
+ * const form = useForm({ title, body }, { dirty: () => editor.state.value?.isDirty === true });
9
+ * <button :disabled="!form.valid || form.submitting" @click="form.submit(() => editor.client.value!.save())">Save</button>
10
+ * ```
11
+ */
12
+ export function useForm(fields, options = {}) {
13
+ const list = formFieldList(fields);
14
+ const submitting = shallowRef(false);
15
+ const state = computed(() => formStateOf(list, toValue(options.dirty) === true, submitting.value));
16
+ return reactive({
17
+ dirty: computed(() => state.value.dirty),
18
+ editing: computed(() => state.value.editing),
19
+ validating: computed(() => state.value.validating),
20
+ pending: computed(() => state.value.pending),
21
+ valid: computed(() => state.value.valid),
22
+ submitting: computed(() => state.value.submitting),
23
+ async submit(command, submitOptions = {}) {
24
+ if (submitting.value)
25
+ return { status: "busy" };
26
+ submitting.value = true;
27
+ try {
28
+ return await submitFields(list, command, submitOptions, index => list[index]);
29
+ }
30
+ finally {
31
+ submitting.value = false;
32
+ }
33
+ },
34
+ async commit() {
35
+ await Promise.all(list.map(field => field.commit()));
36
+ return state.value;
37
+ },
38
+ reset() { for (const field of list)
39
+ field.reset(); },
40
+ });
41
+ }
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { type Component, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from "vue";
2
- import { type BridgeConnectionOptions, type BridgeConnectionState, type BridgeField, type BridgeOperation, type BridgeOutcomeFailure, type FieldBaseline, type FieldDefinition, type FieldState, type FieldOptions, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewClient, type ViewConnector, type ViewSource } from "@runic-artifex/views";
1
+ import { type Component, type ComputedRef, type HTMLAttributes, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from "vue";
2
+ import { type Appearance, type BridgeConnectionOptions, type BridgeConnectionState, type BridgeField, type BridgeOperation, type BridgeOutcomeFailure, type FieldBaseline, type FieldDefinition, type FieldState, type FieldOptions, type LatestOperationController, type LatestOperationState, type OperationController, type OperationControllerOptions, type OperationState, type PageReference, type ViewRegistryPage, type FieldError, type TextReference, type RegionCollection, type RegionEntry, type ViewClient, type ViewConnector, type ViewSource } from "@runic-artifex/views";
3
3
  export interface ViewHandle<TClient extends ViewClient> {
4
4
  /** The latest state, or undefined until the client connects. */
5
5
  readonly state: Readonly<Ref<TClient["snapshot"] | undefined>>;
@@ -60,15 +60,15 @@ export interface SuspenseViewHandle<TClient extends ViewClient> {
60
60
  export declare function useSuspenseView<TClient extends ViewClient>(source: ViewConnector<TClient> | TClient, options?: UseViewOptions<TClient>): Promise<SuspenseViewHandle<TClient>>;
61
61
  /**
62
62
  * A build-known map checks each generated reference kind against its component's `page` prop. A nullable
63
- * reference, such as a region slot's `State["main"]`, checks its non-null kinds.
63
+ * reference, such as a region slot's `State["main"]`, checks its non-null kinds. A component whose `page` is a shared
64
+ * page reference (`[RunicSharedClient]`), such as `ResultPagePageReference`, registers for each of its kinds.
64
65
  */
65
66
  export type ViewRegistry<R extends PageReference | null | undefined> = {
66
- readonly [K in NonNullable<R>["kind"]]: Component<{
67
- page: Extract<NonNullable<R>, {
68
- readonly kind: K;
69
- }>;
70
- }>;
67
+ readonly [K in NonNullable<R>["kind"]]: PageComponent<ViewRegistryPage<R, K>>;
71
68
  };
69
+ type PageComponent<P> = P extends unknown ? Component<{
70
+ page: P;
71
+ }> : never;
72
72
  export interface ViewOutletProps<R extends PageReference> {
73
73
  /** The presented reference, such as `state.main`. */
74
74
  content: R | null | undefined;
@@ -79,7 +79,8 @@ export interface ViewOutletProps<R extends PageReference> {
79
79
  * the reference as its `page` prop. A different reference remounts the
80
80
  * component. The default slot renders while there is no content. A kind without
81
81
  * a component renders the `missing` slot, which receives `{ content }`, for example
82
- * for localized text, or an English alert without it:
82
+ * for localized text. Without the slot, a development build renders an English alert, and a production build
83
+ * renders nothing and reports the kind (`installErrorReporting`, `onBridgeDiagnostic`):
83
84
  *
84
85
  * ```vue
85
86
  * <ViewOutlet :content="state?.main" :registry="pages">
@@ -107,6 +108,61 @@ export declare const ViewOutlet: new <R extends PageReference>(props: (ViewOutle
107
108
  }) | (ViewOutletProps<R> & {
108
109
  [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
109
110
  }), {}, {}, {}, {}, {}>;
111
+ /** How {@link RegionOutlets} renders the regions of a collection. */
112
+ export type RegionOutletsMode = "keep-mounted" | "selected";
113
+ /**
114
+ * Attributes that {@link RegionOutlets} merges onto a region's wrapper, such as `id`, `role` and `aria-labelledby`.
115
+ * `hidden` and `data-region-key` stay controlled by the outlet, and a `style` is merged with its `display: none`.
116
+ */
117
+ export type RegionPanelAttributes = Omit<HTMLAttributes, "hidden"> & {
118
+ readonly [attribute: `data-${string}`]: string | undefined;
119
+ };
120
+ export interface RegionOutletsProps<R extends PageReference> {
121
+ /** The presented region collection, such as `state.documents`. */
122
+ collection: RegionCollection<R> | null | undefined;
123
+ registry: ViewRegistry<R>;
124
+ /**
125
+ * `"keep-mounted"` (the default) renders every region and hides all but the selected one, so each region keeps
126
+ * its component and DOM. `"selected"` renders only the selected region.
127
+ */
128
+ mode?: RegionOutletsMode;
129
+ /**
130
+ * Returns attributes for a region's wrapper, for example `{ id, role: "tabpanel", "aria-labelledby" }`, so a tab
131
+ * can point `aria-controls` at the panel.
132
+ */
133
+ panelProps?: (entry: RegionEntry<R>) => RegionPanelAttributes;
134
+ }
135
+ /**
136
+ * Renders a {@link ViewOutlet} for the regions of a region collection, each in a `<div data-region-key>` keyed by
137
+ * the region's key. A region that is not selected is rendered with `hidden` and an inline `display: none`, which
138
+ * author CSS without `!important` cannot override. A new content reference in a region remounts only that region's
139
+ * component. The default slot renders while the collection has no region, and the
140
+ * `missing` slot is passed to each outlet:
141
+ *
142
+ * ```vue
143
+ * <RegionOutlets :collection="state?.documents" :registry="pages"><p>No open documents</p></RegionOutlets>
144
+ * ```
145
+ */
146
+ export declare const RegionOutlets: new <R extends PageReference>(props: (RegionOutletsProps<R> & ({
147
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
148
+ } | {
149
+ [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
150
+ })) & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps) => import("vue").CreateComponentPublicInstanceWithMixins<RegionOutletsProps<R> & ({
151
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
152
+ } | {
153
+ [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
154
+ }), {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, import("vue").EmitsOptions, import("vue").PublicProps, {}, false, {}, {}, {}, {}, string, {}, any, import("vue").ComponentProvideOptions, {
155
+ P: {};
156
+ B: {};
157
+ D: {};
158
+ C: {};
159
+ M: {};
160
+ Defaults: {};
161
+ }, (RegionOutletsProps<R> & {
162
+ [x: `on${Capitalize<string>}`]: ((...args: any[]) => any) | undefined;
163
+ }) | (RegionOutletsProps<R> & {
164
+ [x: `on${Capitalize<string>}`]: ((...args: never) => any) | undefined;
165
+ }), {}, {}, {}, {}, {}>;
110
166
  export interface CommandHandle<TArgs extends readonly unknown[], TResult, TFailure = BridgeOutcomeFailure<TResult>> {
111
167
  /**
112
168
  * Runs the command. Resolves to its result, including a `BridgeOutcome` with a
@@ -256,6 +312,8 @@ export interface FieldHandle<TValue> {
256
312
  readonly errors: readonly string[];
257
313
  /** The producer's field while a checked write's `conflict` keeps the draft; `undefined` otherwise. */
258
314
  readonly conflict: FieldBaseline<TValue> | undefined;
315
+ /** The member's validation is in progress, such as an asynchronous rule that is still checking: show "checking…". */
316
+ readonly validating: boolean;
259
317
  /** The user changed the value. */
260
318
  input(value: TValue): void;
261
319
  /**
@@ -289,7 +347,7 @@ export interface FieldHandle<TValue> {
289
347
  * conflict holds further writes until `retry()` or `reset()`. Leaving the scope writes a value that waits to be
290
348
  * written.
291
349
  */
292
- export declare function useField<TClient extends ViewClient, TValue>(view: TextFieldView<TClient>, field: BridgeField<NoInfer<TClient>, NoInfer<TClient>["snapshot"], TValue> | FieldDefinition<NoInfer<TClient>, NoInfer<TClient>["snapshot"], TValue>, options?: FieldOptions): FieldHandle<TValue>;
350
+ export declare function useField<TClient extends ViewClient, TValue>(view: TextFieldView<TClient>, field: BridgeField<NoInfer<TClient>, NoInfer<TClient>["snapshot"], TValue> | FieldDefinition<NoInfer<TClient>, NoInfer<TClient>["snapshot"], TValue>, options?: FieldOptions<TValue>): FieldHandle<TValue>;
293
351
  export interface BridgeConnectionHandle {
294
352
  /** The connection to the .NET host, as `onBridgeConnection` reports it. */
295
353
  readonly state: Readonly<Ref<BridgeConnectionState>>;
@@ -306,7 +364,56 @@ export interface BridgeConnectionHandle {
306
364
  * ```
307
365
  */
308
366
  export declare function useBridgeConnection(options?: BridgeConnectionOptions): BridgeConnectionHandle;
367
+ /**
368
+ * A text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the window's
369
+ * language (`resolveText`), as a computed ref that follows a language switch until the effect scope stops. `source` and
370
+ * `fallback` may be refs or getters: `useText(() => view.state.value?.status)`. A string shows as it is; `null` and
371
+ * `undefined` show `fallback`. Configure the page's Translations runtime once with `configureTranslatedText`; without
372
+ * one, a reference shows its fallback text. A field's `FieldError` shows the application's text for it
373
+ * (`configureFieldErrorText`), or its English message: `useText(() => title.error)`.
374
+ *
375
+ * ```vue
376
+ * const status = useText(() => view.state.value?.status);
377
+ * <p>{{ status }}</p>
378
+ * ```
379
+ */
380
+ export declare function useText(source: MaybeRefOrGetter<TextReference | FieldError | string | null | undefined>, fallback?: MaybeRefOrGetter<string | undefined>): ComputedRef<string>;
381
+ /** The window's locale that the application set, or `null` while it sets none, as a ref, until the effect scope stops. */
382
+ export declare function useWindowLocale(): Readonly<Ref<string | null>>;
383
+ /**
384
+ * The page's appearance (`appearance` from `@runic-artifex/views`) as a ref that renders, computes and watches again
385
+ * when it changes: the colour scheme, contrast and reduced motion of the page's engine combined with the desktop's values
386
+ * that a Runic host pushes (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours
387
+ * palette. Follows them while the calling component or effect scope lives; every member is `null` under server
388
+ * rendering.
389
+ *
390
+ * ```ts
391
+ * const look = useAppearance();
392
+ * const animate = computed(() => look.value.reducedMotion !== true);
393
+ * ```
394
+ */
395
+ export declare function useAppearance(): Readonly<Ref<Appearance>>;
396
+ /**
397
+ * The locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's locale),
398
+ * as a ref that renders, computes and watches again when it changes. It is one ref for the page and needs no effect
399
+ * scope, so the page's locale resolver can read it: a template that calls `m.*()` then renders again on a language
400
+ * switch. `undefined` while the page has no Translations runtime and the application sets no window locale.
401
+ *
402
+ * ```ts
403
+ * const textLocale = useTextLocale();
404
+ * configureLocaleResolver(() => textLocale.value ?? locale.getLocale());
405
+ * ```
406
+ */
407
+ export declare function useTextLocale(): Readonly<Ref<string | undefined>>;
309
408
  export { useCollectionViewport, type CollectionViewportHandle } from "./viewport.js";
409
+ export { useForm, type FormFieldHandle, type FormHandle, type UseFormOptions } from "./form.js";
410
+ export { commitAllFields, type FormState, type FormSubmitOptions, type FormSubmitResult } from "@runic-artifex/views";
411
+ export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, type DocumentLocaleOptions, type FieldErrorArguments, type FieldErrorReason, type FieldErrorText, type TextReference, type TextTranslations, } from "@runic-artifex/views";
412
+ export { appearance, onAppearance, type Appearance, type AppearanceColorScheme, type AppearanceContrast, type AppearanceSystemColors, type HostAppearance, } from "@runic-artifex/views";
413
+ export { useQueryCollection, type QueryCollectionHandle } from "./query.js";
310
414
  export { onBridgeConnection, type BridgeConnectionOptions, type BridgeConnectionState } from "@runic-artifex/views";
311
- export { FieldError, type BridgeField, type BridgeFieldKind, type FieldBaseline, type FieldDefinition, type FieldErrorKind, type FieldOptions, type FieldState, } from "@runic-artifex/views";
415
+ export { upload, type BlobRef, type RunicBlob, type UploadOptions, type UploadProgress } from "@runic-artifex/views";
416
+ export { regionEntries, selectedRegion, type RegionCollection, type RegionEntry, type RegionOutcome, type RegionSlot, } from "@runic-artifex/views";
417
+ export { installBackNavigation, installNavigationPath, navigateBack, onNavigationPath, openNavigationPath, type NavigationPathChange, type NavigationPathOptions, type NavigationReply, } from "@runic-artifex/views";
418
+ export { FieldError, type BridgeField, type BridgeFieldConstraints, type BridgeFieldKind, type FieldBaseline, type FieldDefinition, type FieldErrorKind, type FieldOptions, type FieldState, } from "@runic-artifex/views";
312
419
  export { useMenuBar, type MenuBarEntry, type MenuBarHandle, type MenuBarInvokeResult, type MenuBarItem, type MenuBarMenu, type MenuBarRequest, type MenuBarSeparator, type MenuBarState, type UseMenuBarOptions, } from "./menu-bar.js";
package/dist/index.js CHANGED
@@ -1,6 +1,7 @@
1
- import { computed, defineComponent, h, reactive, shallowRef, toValue, watch, } from "vue";
2
- import { createCommandController, createLatestOperationController, createOperationController, createFieldController, createTextFieldController, createViewController, onBridgeConnection, } from "@runic-artifex/views";
3
- import { viewSourceIdentity } from "@runic-artifex/views/bindings";
1
+ import { computed, customRef, defineComponent, h, reactive, shallowRef, toValue, watch, } from "vue";
2
+ import { createCommandController, createLatestOperationController, createOperationController, createFieldController, createTextFieldController, createViewController, onBridgeConnection, onWindowLocale, appearance, onAppearance, resolveText, subscribeText, textLocale, windowLocale, regionEntries, } from "@runic-artifex/views";
3
+ import { missingViewMessage, reportMissingView, viewSourceIdentity } from "@runic-artifex/views/bindings";
4
+ import { isDevelopment } from "./development.js";
4
5
  import { releaseWithScope } from "./scope.js";
5
6
  function controllerOptions(options) {
6
7
  return { ...(options.release ? { release: options.release } : {}), ...(options.keepAlive === undefined ? {} : { keepAlive: options.keepAlive }) };
@@ -70,7 +71,8 @@ function referenceKey(reference) {
70
71
  * the reference as its `page` prop. A different reference remounts the
71
72
  * component. The default slot renders while there is no content. A kind without
72
73
  * a component renders the `missing` slot, which receives `{ content }`, for example
73
- * for localized text, or an English alert without it:
74
+ * for localized text. Without the slot, a development build renders an English alert, and a production build
75
+ * renders nothing and reports the kind (`installErrorReporting`, `onBridgeDiagnostic`):
74
76
  *
75
77
  * ```vue
76
78
  * <ViewOutlet :content="state?.main" :registry="pages">
@@ -86,10 +88,36 @@ export const ViewOutlet = defineComponent((props, { slots }) => () => {
86
88
  if (!component) {
87
89
  if (slots["missing"])
88
90
  return slots["missing"]({ content });
89
- return h("p", { role: "alert" }, `No web component is registered for ${content.kind}.`);
91
+ if (isDevelopment())
92
+ return h("p", { role: "alert" }, missingViewMessage(content.kind));
93
+ reportMissingView(content.kind);
94
+ return null;
90
95
  }
91
96
  return h(component, { key: referenceKey(content), page: content });
92
97
  }, { name: "ViewOutlet", props: ["content", "registry"] });
98
+ /**
99
+ * Renders a {@link ViewOutlet} for the regions of a region collection, each in a `<div data-region-key>` keyed by
100
+ * the region's key. A region that is not selected is rendered with `hidden` and an inline `display: none`, which
101
+ * author CSS without `!important` cannot override. A new content reference in a region remounts only that region's
102
+ * component. The default slot renders while the collection has no region, and the
103
+ * `missing` slot is passed to each outlet:
104
+ *
105
+ * ```vue
106
+ * <RegionOutlets :collection="state?.documents" :registry="pages"><p>No open documents</p></RegionOutlets>
107
+ * ```
108
+ */
109
+ export const RegionOutlets = defineComponent((props, { slots }) => () => {
110
+ const mode = props.mode ?? "keep-mounted";
111
+ const shown = regionEntries(props.collection).filter(region => mode === "keep-mounted" || region.selected);
112
+ if (shown.length === 0)
113
+ return slots.default?.();
114
+ const missing = slots["missing"];
115
+ return shown.map(region => {
116
+ const panel = props.panelProps?.(region) ?? {};
117
+ const hidden = !region.selected;
118
+ return h("div", { ...panel, key: region.key, "data-region-key": region.key, hidden, style: hidden ? [panel.style, { display: "none" }] : panel.style }, h((ViewOutlet), { content: region.content, registry: props.registry }, missing ? { missing } : {}));
119
+ });
120
+ }, { name: "RegionOutlets", props: ["collection", "registry", "mode", "panelProps"] });
93
121
  /**
94
122
  * Tracks a command's pending state and failure as shallow refs, like `useView`,
95
123
  * so the handle can be destructured. Call it in `setup()` or `effectScope().run()`
@@ -259,6 +287,7 @@ export function useField(view, field, options = {}) {
259
287
  error: computed(() => current.value.error),
260
288
  errors: computed(() => current.value.errors),
261
289
  conflict: computed(() => current.value.conflict),
290
+ validating: computed(() => current.value.validating),
262
291
  input: (value) => controller.input(value),
263
292
  commit: () => controller.commit(),
264
293
  retry: () => controller.retry(),
@@ -282,7 +311,89 @@ export function useBridgeConnection(options = {}) {
282
311
  releaseWithScope("useBridgeConnection", stop);
283
312
  return { state };
284
313
  }
314
+ /**
315
+ * A text reference that a ViewModel produced, such as a status line or a validation message's `text`, in the window's
316
+ * language (`resolveText`), as a computed ref that follows a language switch until the effect scope stops. `source` and
317
+ * `fallback` may be refs or getters: `useText(() => view.state.value?.status)`. A string shows as it is; `null` and
318
+ * `undefined` show `fallback`. Configure the page's Translations runtime once with `configureTranslatedText`; without
319
+ * one, a reference shows its fallback text. A field's `FieldError` shows the application's text for it
320
+ * (`configureFieldErrorText`), or its English message: `useText(() => title.error)`.
321
+ *
322
+ * ```vue
323
+ * const status = useText(() => view.state.value?.status);
324
+ * <p>{{ status }}</p>
325
+ * ```
326
+ */
327
+ export function useText(source, fallback) {
328
+ const version = shallowRef(0);
329
+ releaseWithScope("useText", subscribeText(() => { version.value++; }));
330
+ return computed(() => {
331
+ void version.value;
332
+ return resolveText(toValue(source), toValue(fallback));
333
+ });
334
+ }
335
+ /** The window's locale that the application set, or `null` while it sets none, as a ref, until the effect scope stops. */
336
+ export function useWindowLocale() {
337
+ const locale = shallowRef(windowLocale());
338
+ releaseWithScope("useWindowLocale", onWindowLocale(next => { locale.value = next; }));
339
+ return locale;
340
+ }
341
+ /**
342
+ * The page's appearance (`appearance` from `@runic-artifex/views`) as a ref that renders, computes and watches again
343
+ * when it changes: the colour scheme, contrast and reduced motion of the page's engine combined with the desktop's values
344
+ * that a Runic host pushes (`appearance/1`), which also carry the text scale, the accent colour and the forced-colours
345
+ * palette. Follows them while the calling component or effect scope lives; every member is `null` under server
346
+ * rendering.
347
+ *
348
+ * ```ts
349
+ * const look = useAppearance();
350
+ * const animate = computed(() => look.value.reducedMotion !== true);
351
+ * ```
352
+ */
353
+ export function useAppearance() {
354
+ const current = shallowRef(appearance());
355
+ releaseWithScope("useAppearance", onAppearance(next => { current.value = next; }));
356
+ current.value = appearance();
357
+ return current;
358
+ }
359
+ let pageTextLocale;
360
+ /**
361
+ * The locale that text is shown in (`textLocale`: the page's Translations locale, which follows the window's locale),
362
+ * as a ref that renders, computes and watches again when it changes. It is one ref for the page and needs no effect
363
+ * scope, so the page's locale resolver can read it: a template that calls `m.*()` then renders again on a language
364
+ * switch. `undefined` while the page has no Translations runtime and the application sets no window locale.
365
+ *
366
+ * ```ts
367
+ * const textLocale = useTextLocale();
368
+ * configureLocaleResolver(() => textLocale.value ?? locale.getLocale());
369
+ * ```
370
+ */
371
+ export function useTextLocale() {
372
+ return pageTextLocale ??= customRef((track, trigger) => {
373
+ let subscribed = false;
374
+ return {
375
+ get() {
376
+ if (!subscribed) {
377
+ subscribed = true;
378
+ subscribeText(trigger);
379
+ }
380
+ track();
381
+ return textLocale();
382
+ },
383
+ set() { },
384
+ };
385
+ });
386
+ }
285
387
  export { useCollectionViewport } from "./viewport.js";
388
+ export { useForm } from "./form.js";
389
+ export { commitAllFields } from "@runic-artifex/views";
390
+ export { configureFieldErrorText, configureTranslatedText, fieldErrorText, resolveText, syncDocumentLocale, textDirection, windowLocale, } from "@runic-artifex/views";
391
+ export { appearance, onAppearance, } from "@runic-artifex/views";
392
+ export { useQueryCollection } from "./query.js";
286
393
  export { onBridgeConnection } from "@runic-artifex/views";
394
+ // blobs/1: uploads from the page and the blob values of state.
395
+ export { upload } from "@runic-artifex/views";
396
+ export { regionEntries, selectedRegion, } from "@runic-artifex/views";
397
+ export { installBackNavigation, installNavigationPath, navigateBack, onNavigationPath, openNavigationPath, } from "@runic-artifex/views";
287
398
  export { FieldError, } from "@runic-artifex/views";
288
399
  export { useMenuBar, } from "./menu-bar.js";
@@ -0,0 +1,23 @@
1
+ import { type ComponentPublicInstance, type MaybeRefOrGetter, type Ref } from "vue";
2
+ import { type QueryCollection, type QueryViewport, type QueryViewportOptions, type RunicQuery } from "@runic-artifex/views";
3
+ export interface QueryCollectionHandle<TRow> {
4
+ /** The rows to render with their offsets, the spacer's `totalSize`, the total, query, loading and error state. */
5
+ readonly viewport: Readonly<Ref<QueryViewport<TRow>>>;
6
+ /** A function ref for the scroll container, bound to a native element: `<div :ref="attach">`. */
7
+ attach(element: Element | ComponentPublicInstance | null): void;
8
+ /** A function ref for each rendered row, which measures its height: `<div :ref="el => measure(el, item.index)">`. */
9
+ measure(element: Element | ComponentPublicInstance | null, index: number): void;
10
+ /** Scrolls to the row with `key` in the current query; resolves `false` when no row has it. */
11
+ scrollToKey(key: string, align?: "start" | "center" | "end"): Promise<boolean>;
12
+ scrollToIndex(index: number, align?: "start" | "center" | "end"): void;
13
+ /** Changes the collection's sort and filter (ViewModel state every presentation shares). */
14
+ setQuery(query: RunicQuery): Promise<void>;
15
+ /** Loads the range again after a failure. */
16
+ retry(): void;
17
+ }
18
+ /**
19
+ * Follows a scroll container for a query collection (`client.queries.{name}`): it loads the rows the container shows
20
+ * from .NET, with placeholders until they arrive, and lays them out with variable heights. Pass the collection or a
21
+ * getter of it (`() => client.value?.queries.rows`). Call it in `setup()` or `effectScope().run()`.
22
+ */
23
+ export declare function useQueryCollection<TRow>(collection: MaybeRefOrGetter<QueryCollection<TRow> | undefined>, options: MaybeRefOrGetter<QueryViewportOptions>): QueryCollectionHandle<TRow>;
package/dist/query.js ADDED
@@ -0,0 +1,67 @@
1
+ import { shallowRef, toValue, watch } from "vue";
2
+ import { createQueryViewportController, } from "@runic-artifex/views";
3
+ import { releaseWithScope } from "./scope.js";
4
+ /**
5
+ * Follows a scroll container for a query collection (`client.queries.{name}`): it loads the rows the container shows
6
+ * from .NET, with placeholders until they arrive, and lays them out with variable heights. Pass the collection or a
7
+ * getter of it (`() => client.value?.queries.rows`). Call it in `setup()` or `effectScope().run()`.
8
+ */
9
+ export function useQueryCollection(collection, options) {
10
+ const empty = { items: [], totalSize: 0, total: null, query: { sort: [], filters: [] }, loading: false, error: undefined };
11
+ const viewport = shallowRef(empty);
12
+ let controller;
13
+ let stop;
14
+ let container = null;
15
+ const rows = new Map();
16
+ const release = () => {
17
+ stop?.();
18
+ stop = undefined;
19
+ for (const unobserve of rows.values())
20
+ unobserve();
21
+ rows.clear();
22
+ controller?.dispose();
23
+ controller = undefined;
24
+ };
25
+ watch(() => toValue(collection), next => {
26
+ release();
27
+ if (!next) {
28
+ viewport.value = empty;
29
+ return;
30
+ }
31
+ const created = controller = createQueryViewportController(next, toValue(options));
32
+ stop = created.subscribe(() => { viewport.value = created.current; });
33
+ created.attach(container);
34
+ viewport.value = created.current;
35
+ }, { immediate: true });
36
+ watch(() => {
37
+ const { estimateSize, overscan } = toValue(options);
38
+ return [estimateSize, overscan];
39
+ }, ([estimateSize, overscan]) => {
40
+ controller?.update({ estimateSize, ...(overscan === undefined ? {} : { overscan }) });
41
+ });
42
+ releaseWithScope("useQueryCollection", release);
43
+ const element = (value) => typeof HTMLElement !== "undefined" && value instanceof HTMLElement ? value : null;
44
+ return {
45
+ viewport,
46
+ attach(value) {
47
+ container = element(value);
48
+ controller?.attach(container);
49
+ },
50
+ measure(value, index) {
51
+ rows.get(index)?.();
52
+ rows.delete(index);
53
+ const row = element(value);
54
+ if (row && controller)
55
+ rows.set(index, controller.observe(row, index));
56
+ },
57
+ scrollToKey: async (key, align) => controller ? controller.scrollToKey(key, align) : false,
58
+ scrollToIndex: (index, align) => controller?.scrollToIndex(index, align),
59
+ setQuery: async (query) => {
60
+ const current = toValue(collection);
61
+ if (!current)
62
+ throw new TypeError("useQueryCollection has no collection yet.");
63
+ await current.setQuery(query);
64
+ },
65
+ retry: () => toValue(collection)?.retry(),
66
+ };
67
+ }
package/dist/scope.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { getCurrentScope, onScopeDispose } from "vue";
2
+ import { isDevelopment } from "./development.js";
2
3
  // Ties a composable's controller to the current effect scope. Outside one (not
3
4
  // in setup() or effectScope().run()) nothing ever releases it, so development
4
5
  // builds say so.
@@ -7,7 +8,7 @@ export function releaseWithScope(composable, release) {
7
8
  onScopeDispose(release);
8
9
  return;
9
10
  }
10
- if (process.env.NODE_ENV !== "production")
11
+ if (isDevelopment())
11
12
  console.warn(`${composable} was called outside an active effect scope, so nothing releases it: ` +
12
13
  "call it in a component's setup() or inside effectScope().run(), and stop that scope to release it.");
13
14
  }
package/dist/viewport.js CHANGED
@@ -1,6 +1,7 @@
1
1
  import { shallowRef, toValue, watch } from "vue";
2
2
  import { createCollectionViewportController, } from "@runic-artifex/views";
3
3
  import { releaseWithScope } from "./scope.js";
4
+ import { isDevelopment } from "./development.js";
4
5
  /**
5
6
  * Follows a fixed-row-height scroll container and returns the rows to request
6
7
  * from .NET. Pass a getter such as `() => ({ totalCount: state.value?.totalCount ?? 0, rowHeight: 32 })`
@@ -26,7 +27,7 @@ export function useCollectionViewport(options) {
26
27
  if (typeof HTMLElement === "undefined")
27
28
  return controller.attach(null);
28
29
  const container = element instanceof HTMLElement ? element : null;
29
- if (process.env.NODE_ENV !== "production" && element !== null && container === null && !warned) {
30
+ if (isDevelopment() && element !== null && container === null && !warned) {
30
31
  warned = true;
31
32
  console.warn("useCollectionViewport's attach received a component instance or a non-HTML element, so the viewport " +
32
33
  "is detached: bind `:ref=\"attach\"` to a native scroll container such as a <div>.");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@runic-artifex/vue",
3
- "version": "0.15.1",
3
+ "version": "0.17.0",
4
4
  "description": "Vue composables for generated Runic Views clients",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -30,10 +30,10 @@
30
30
  },
31
31
  "peerDependencies": {
32
32
  "vue": ">=3.5.30 <4",
33
- "@runic-artifex/views": "0.15.1"
33
+ "@runic-artifex/views": "0.17.0"
34
34
  },
35
35
  "devDependencies": {
36
- "@runic-artifex/views": "0.15.1",
36
+ "@runic-artifex/views": "0.17.0",
37
37
  "esbuild": "0.28.2",
38
38
  "happy-dom": "21.0.4",
39
39
  "playwright-core": "1.63.0",
@@ -50,7 +50,7 @@
50
50
  "url": "git+https://github.com/Runic-Artifex/runic-sdk.git",
51
51
  "directory": "packages/web/vue"
52
52
  },
53
- "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.15.1/packages/web/vue#readme",
53
+ "homepage": "https://github.com/Runic-Artifex/runic-sdk/tree/v0.17.0/packages/web/vue#readme",
54
54
  "bugs": {
55
55
  "url": "https://github.com/Runic-Artifex/runic-sdk/issues"
56
56
  },
@@ -60,5 +60,5 @@
60
60
  "views",
61
61
  "vue"
62
62
  ],
63
- "gitHead": "fce42f47296a4784532fbba0fec9602cd3778fbb"
63
+ "gitHead": "daeb17e5c3fb0b625d5d988d359cd12ffa51f8c6"
64
64
  }