feat: #542 support binding to regular collection navigation properties with c-select.

Author: ascott18

CHANGELOG.md

@@ -21,6 +21,7 @@
 - `c-datetime-picker`: Added prop `showTodayButton`
 - `c-input`: Added a `filter` prop to for enum inputs to restrict the values available for selection.
 - `c-select`: When bound to a `ViewModel` or `ViewModelCollection`, selected items are converted to `ViewModel` instances before being emitted so that event handlers will receive the final object instance, rather than the intermediate plain model instance.
+- `c-select`: Now supports bound to a non-many-to-many collection navigation property. Selecting an item will populate the foreign key of the dependent item, and deselecting an item will clear the foreign key. This mechanism is only available when using c-select directly - it is not delegated by c-input.
 - `c-select-many-to-many`: The `itemTitle` prop now receives the existing selected middle entity instance, if there is one.
 
 ## Fixes

docs/stacks/vue/coalesce-vue-vuetify/components/c-select.md

@@ -10,7 +10,7 @@ Used for selecting values for foreign key and navigation properties, or for sele
 
 ## Examples
 
-Binding to a navigation property or foreign key of a model:
+Binding to a reference navigation property or foreign key of a model:
 
 ``` vue-html
   <c-select :model="person" for="company" />
@@ -40,6 +40,16 @@ Multi-select:
   <c-select for="Person" multiple v-model:object-value="selectedPeople" />
 ```
 
+Binding to a collection navigation property of a model:
+
+``` vue-html
+  <c-select :model="person" for="casesAssigned" />
+```
+
+This will assign `person` and its PK to the inverse navigation property of the relationship (`Case.AssignedTo`) when items are selected, and will null those properties when items are deselected. Note that this scenario is not delegated to by `c-input` automatically and requires direct usage of `c-select` since it is a fairly unusual scenario and usually requires additional customization (e.g. the `params` and `create` props) to make it function well.
+
+----
+
 Examples of other props:
 
 ``` vue-html
@@ -61,12 +71,12 @@ Examples of other props:
 
 Note: In addition to the below props, `c-select` also supports most props that are supported by Vuetify's [v-text-field](https://vuetifyjs.com/en/components/text-fields/).
 
-<Prop def="for: string | ForeignKeyProperty | ModelReferenceNavigationProperty | ModelType" lang="ts" />
+<Prop def="for: string | Value | Property | ModelType" lang="ts" />
 
 A metadata specifier for the value being bound. One of:
 
-- The name of a foreign key or reference navigation property belonging to `model`. 
 - The name of a model type.
+- The name of a foreign key or navigation property belonging to `model`. 
 - A direct reference to a metadata object.
 
 ::: tip

docs/stacks/vue/coalesce-vue-vuetify/overview.md

@@ -18,7 +18,7 @@ If for whatever reason you find yourself adding Coalesce to an existing project,
 ## Display Components
 
 <table>
-<thead><tr><th width="170px">Component</th><th>Description</th></tr></thead>
+<thead><tr><th width="170px">Component</th><th>Description</th></tr></thead><tbody>
 <tr><td>
 
 [c-display](./components/c-display.md)
@@ -51,13 +51,13 @@ If for whatever reason you find yourself adding Coalesce to an existing project,
 
 @[import-md "after":"MARKER:summary", "before":"MARKER:summary-end"](./components/c-table.md) 
 </td></tr>
-</table>
+</tbody></table>
 
 
 ## Input Components
 
 <table>
-<thead><tr><th width="170px">Component</th><th>Description</th></tr></thead>
+<thead><tr><th width="170px">Component</th><th>Description</th></tr></thead><tbody>
 <tr><td>
 
 [c-input](./components/c-input.md)
@@ -139,13 +139,13 @@ If for whatever reason you find yourself adding Coalesce to an existing project,
 @[import-md "after":"MARKER:summary", "before":"MARKER:summary-end"](./components/c-list-page.md) 
 </td></tr>
 
-</table>
+</tbody></table>
 
 
 ## Admin Components
 
 <table>
-<thead><tr><th width="170px">Component</th><th>Description</th></tr></thead>
+<thead><tr><th width="170px">Component</th><th>Description</th></tr></thead><tbody>
 <tr><td>
 
 [c-admin-method](./components/c-admin-method.md)
@@ -217,4 +217,4 @@ If for whatever reason you find yourself adding Coalesce to an existing project,
 
 @[import-md "after":"MARKER:summary", "before":"MARKER:summary-end"](./components/c-admin-audit-log-page.md) 
 </td></tr>
-</table>
+</tbody></table>

playground/Coalesce.Web.Vue3/src/examples/c-select/multiple-binding.vue

@@ -18,8 +18,12 @@
         v-model:objectValue="selectedModels"
         open-on-clear
         :create="{
-          getLabel(search: string, items: Person[]) { return items.length == 0 ? search : false },
-          async getItem(search: string, label: string) { return new Person({ name: label }) }
+          getLabel(search: string, items: Person[]) {
+            return items.length == 0 ? search : false;
+          },
+          async getItem(search: string, label: string) {
+            return new Person({ name: label });
+          },
         }"
       ></c-select>
     </v-col>
@@ -66,7 +70,22 @@
     </v-col>
   </v-row>
 
-  <h1>plain v-autocomplete multiple</h1>
+  <h1>for non-many-to-many collection navigation</h1>
+  <v-row v-if="person">
+    <v-col>
+      <c-select :model="person" for="casesAssigned" />
+      <h3>Via c-input</h3>
+      <c-input :model="person" for="casesAssigned" />
+    </v-col>
+    <v-col>
+      <v-btn @click="person.$bulkSave()"> Save </v-btn>
+      <div>
+        <c-display :model="person" for="casesAssigned" />
+      </div>
+    </v-col>
+  </v-row>
+
+  <h1>plain v-autocomplete multiple (for styling/visual reference)</h1>
   <v-row>
     <v-col>
       <v-autocomplete
@@ -87,9 +106,9 @@
 
 <script setup lang="ts">
 import { Case, Person } from "@/models.g";
-import { PersonListViewModel } from "@/viewmodels.g";
+import { PersonListViewModel, PersonViewModel } from "@/viewmodels.g";
 import { modelDisplay, useBindToQueryString } from "coalesce-vue";
-import { ref } from "vue";
+import { computed, ref } from "vue";
 
 const selectedIds = ref<number[]>([]);
 useBindToQueryString(selectedIds, {
@@ -101,6 +120,9 @@ useBindToQueryString(selectedIds, {
 const personList = new PersonListViewModel();
 personList.methodWithEntityParameter.args.person = new Person({ companyId: 1 });
 
+personList.$load();
+const person = computed(() => personList.$items[0]);
+
 const caseVm = new Case();
 const selectedModels = ref<Person[]>([]);
 

src/coalesce-vue-vuetify3/src/components/input/c-select.spec.tsx

@@ -25,11 +25,13 @@ import {
   Company,
   ComplexModel,
   EnumPkId,
+  Person,
   Test,
 } from "@test-targets/models.g";
 import {
   CaseViewModel,
   ComplexModelViewModel,
+  PersonViewModel,
   TestViewModel,
 } from "@test-targets/viewmodels.g";
 
@@ -118,13 +120,20 @@ describe("CSelect", () => {
     // Against models that might be null
     () => <CSelect model={complexVm.referenceNavigation} for="referenceNavigation" />;
 
+    // Binding to collection navigation
+    () => <CSelect model={new Person} for="casesAssigned" />;
+
+    // Unfortunately, after adding support for binding to non-many-to-many collection navigation props,
+    // there doesn't seem to be any practical way to exclude manyToMany props anymore with TS.
+    // This is still a runtime error, but we can't enforce it with types.
+    // // @ts-expect-error Cannot bind to many-to-many
+    // () => <CSelect model={new Case} for="caseProducts" />;
+
     // Binding to plain Models:
     () => <CSelect model={model} for="singleTest" />;
     () => <CSelect model={model} for="singleTestId" />;
     //@ts-expect-error wrong type of property
     () => <CSelect model={model} for="name" />;
-    //@ts-expect-error Cannot bind to many-to-many
-    () => <CSelect model={new Case} for="caseProducts" />;
     //@ts-expect-error wrong type of property
     () => <CSelect model={complexVm} for={complexVm.$metadata.props.name} />;
 
@@ -675,11 +684,119 @@ describe("CSelect", () => {
 
       // Assert
       expect(model.tests).toHaveLength(1);
-      expect(model.tests[0].testId).toBe(101);
+      const selectedItem = model.tests[0];
+      expect(selectedItem.testId).toBe(101);
 
       // Emitted event value should exactly equal by instance the resulting value on `model`.
-      expect(onUpdateObject.mock.calls[0][0][0]).toBe(model.tests[0]);
-      expect(onSelectionChanged.mock.calls[0][0][0]).toBe(model.tests[0]);
+      expect(onUpdateObject.mock.calls[0][0][0]).toBe(selectedItem);
+      expect(onSelectionChanged.mock.calls[0][0][0]).toBe(selectedItem);
+    });
+
+    test.each(["menu", "chip"])(
+      "deselect by %s click emits existing ViewModel",
+      async (method) => {
+        // Arrange
+        const model = new ComplexModelViewModel({ singleTestId: 303 });
+        const onSelectionChanged = vitest.fn();
+        const wrapper = mountApp(() => (
+          <CSelect
+            for="Test"
+            multiple
+            onUpdate:modelValue={(v) => (model.tests = v)}
+            modelValue={model.tests}
+            onSelectionChanged={onSelectionChanged}
+          ></CSelect>
+        )).findComponent(CSelect);
+
+        // Act
+        await selectFirstResult(wrapper);
+        const selectedItem = model.tests[0];
+
+        method == "menu"
+          ? await deselectMenuResult(wrapper, 0)
+          : await deselectChipResult(wrapper, 0);
+
+        // Assert
+        // Emitted event value should exactly equal by instance the resulting value on `model`.
+        expect(onSelectionChanged.mock.calls[0][0][0]).toBe(selectedItem);
+        expect(onSelectionChanged.mock.calls[1][0][0]).toBe(selectedItem);
+        expect(selectedItem).toBeInstanceOf(TestViewModel);
+      }
+    );
+
+    test("collectionNavigation binding sets inverse nav on select", async () => {
+      // Arrange
+      const model = new ComplexModelViewModel().$loadCleanData({
+        complexModelId: 1,
+      });
+
+      const wrapper = mountApp(() => (
+        <CSelect model={model} for="tests"></CSelect>
+      )).findComponent(CSelect);
+
+      // Act
+      await selectFirstResult(wrapper);
+
+      // Assert
+      expect(model.tests).toHaveLength(1);
+      const added = model.tests[0];
+      expect(added.complexModel).toBe(model);
+      expect(added.complexModelId).toBe(model.complexModelId);
+
+      expect(model.$bulkSavePreview().items).toEqual([
+        {
+          action: "none",
+          data: { complexModelId: 1 },
+          refs: { complexModelId: model.$stableId },
+          root: true,
+          type: "ComplexModel",
+        },
+        {
+          action: "save",
+          data: { complexModelId: 1, testId: 101 },
+          refs: { testId: added.$stableId },
+          type: "Test",
+        },
+      ]);
+    });
+
+    test("collectionNavigation clears inverse nav on deselect", async () => {
+      // Arrange
+      const model = new ComplexModelViewModel().$loadCleanData({
+        complexModelId: 1,
+        tests: [{ testId: 101, testName: "foo 101", complexModelId: 2 }],
+      });
+
+      const wrapper = mountApp(() => (
+        <CSelect model={model} for="tests"></CSelect>
+      )).findComponent(CSelect);
+
+      // Act
+      await deselectChipResult(wrapper, 0);
+
+      // Assert
+      expect(model.tests).toHaveLength(0);
+      const removed = model.$removedItems![0] as TestViewModel;
+      expect(removed).not.toBeUndefined();
+      expect(removed).toBeInstanceOf(TestViewModel);
+      expect(removed.complexModel).toBeNull();
+      expect(removed.complexModelId).toBeNull();
+
+      expect(model.$bulkSavePreview().items).toEqual([
+        {
+          action: "none",
+          data: { complexModelId: 1 },
+          refs: { complexModelId: model.$stableId },
+          root: true,
+          type: "ComplexModel",
+        },
+        {
+          action: "save",
+          data: { complexModelId: null, testId: 101 },
+          refs: { testId: removed.$stableId },
+          type: "Test",
+        },
+      ]);
     });
   });
 
@@ -949,3 +1066,10 @@ async function selectFirstResult(wrapper: VueWrapper) {
   const overlay = await openMenu(wrapper);
   await overlay.find(".v-list-item").trigger("click");
 }
+async function deselectChipResult(wrapper: VueWrapper, idx: number) {
+  await wrapper.findAll(".v-chip__close")[idx].trigger("click");
+}
+async function deselectMenuResult(wrapper: VueWrapper, idx: number) {
+  const overlay = await openMenu(wrapper);
+  await overlay.findAll(".v-list-item--active")[idx].trigger("click");
+}