From 22e10c234044e9f60955d35baad2ac1ab42614e7 Mon Sep 17 00:00:00 2001
From: Laila Los <44241786+ElectronicBlueberry@users.noreply.github.com>
Date: Thu, 17 Nov 2022 17:16:50 +0100
Subject: [PATCH 1/4] unify composable naming

---
 client/src/components/AboutGalaxy.vue                         | 2 +-
 client/src/components/Panels/Common/ToolSection.test.js       | 4 ++--
 client/src/components/Panels/Common/ToolSection.vue           | 2 +-
 client/src/components/Tool/ToolSourceMenuItem.vue             | 2 +-
 .../Workflow/Invocation/Export/ExportToRemoteButton.vue       | 2 +-
 .../Workflow/Invocation/Export/InvocationExportPluginCard.vue | 2 +-
 client/src/composables/{useConfig.js => config.js}            | 0
 client/src/composables/{useMarkdown.js => markdown.js}        | 0
 .../src/composables/{useMarkdown.test.js => markdown.test.js} | 2 +-
 client/src/composables/{useTaskMonitor.js => taskMonitor.js}  | 0
 .../{useTaskMonitor.test.js => taskMonitor.test.js}           | 2 +-
 11 files changed, 9 insertions(+), 9 deletions(-)
 rename client/src/composables/{useConfig.js => config.js} (100%)
 rename client/src/composables/{useMarkdown.js => markdown.js} (100%)
 rename client/src/composables/{useMarkdown.test.js => markdown.test.js} (94%)
 rename client/src/composables/{useTaskMonitor.js => taskMonitor.js} (100%)
 rename client/src/composables/{useTaskMonitor.test.js => taskMonitor.test.js} (97%)

diff --git a/client/src/components/AboutGalaxy.vue b/client/src/components/AboutGalaxy.vue
index 0337f516326..0555f27fc5c 100644
--- a/client/src/components/AboutGalaxy.vue
+++ b/client/src/components/AboutGalaxy.vue
@@ -5,7 +5,7 @@
 import { computed } from "vue";
 
 import { getAppRoot } from "onload/loadConfig";
-import { useConfig } from "composables/useConfig";
+import { useConfig } from "composables/config";
 import UtcDate from "components/UtcDate";
 import License from "components/License/License";
 import ExternalLink from "components/ExternalLink";
diff --git a/client/src/components/Panels/Common/ToolSection.test.js b/client/src/components/Panels/Common/ToolSection.test.js
index 864df3405bb..04e0dca33ac 100644
--- a/client/src/components/Panels/Common/ToolSection.test.js
+++ b/client/src/components/Panels/Common/ToolSection.test.js
@@ -2,9 +2,9 @@ import { mount } from "@vue/test-utils";
 import { getLocalVue } from "jest/helpers";
 import ToolSection from "./ToolSection";
 
-import { useConfig } from "composables/useConfig";
+import { useConfig } from "composables/config";
 
-jest.mock("composables/useConfig");
+jest.mock("composables/config");
 useConfig.mockReturnValue({
     config: {
         toolbox_auto_sort: true,
diff --git a/client/src/components/Panels/Common/ToolSection.vue b/client/src/components/Panels/Common/ToolSection.vue
index 8799d1235a7..f02fc438f18 100644
--- a/client/src/components/Panels/Common/ToolSection.vue
+++ b/client/src/components/Panels/Common/ToolSection.vue
@@ -53,7 +53,7 @@ import ToolPanelLabel from "./ToolPanelLabel";
 import ariaAlert from "utils/ariaAlert";
 import ToolPanelLinks from "./ToolPanelLinks";
 
-import { useConfig } from "composables/useConfig";
+import { useConfig } from "composables/config";
 
 export default {
     name: "ToolSection",
diff --git a/client/src/components/Tool/ToolSourceMenuItem.vue b/client/src/components/Tool/ToolSourceMenuItem.vue
index def1e910370..d774c2c58eb 100644
--- a/client/src/components/Tool/ToolSourceMenuItem.vue
+++ b/client/src/components/Tool/ToolSourceMenuItem.vue
@@ -1,6 +1,6 @@
 <script setup>
 import ToolSource from "./ToolSource.vue";
-import { useConfig } from "composables/useConfig";
+import { useConfig } from "composables/config";
 import { useCurrentUser } from "composables/user";
 import { FontAwesomeIcon } from "@fortawesome/vue-fontawesome";
 
diff --git a/client/src/components/Workflow/Invocation/Export/ExportToRemoteButton.vue b/client/src/components/Workflow/Invocation/Export/ExportToRemoteButton.vue
index d79d9f3202c..ba2a3951195 100644
--- a/client/src/components/Workflow/Invocation/Export/ExportToRemoteButton.vue
+++ b/client/src/components/Workflow/Invocation/Export/ExportToRemoteButton.vue
@@ -1,7 +1,7 @@
 <script setup>
 import { watch } from "vue";
 import { BButton } from "bootstrap-vue";
-import { useTaskMonitor } from "composables/useTaskMonitor";
+import { useTaskMonitor } from "composables/taskMonitor";
 import { FontAwesomeIcon } from "@fortawesome/vue-fontawesome";
 
 const { isRunning, isCompleted, hasFailed, requestHasFailed, waitForTask } = useTaskMonitor();
diff --git a/client/src/components/Workflow/Invocation/Export/InvocationExportPluginCard.vue b/client/src/components/Workflow/Invocation/Export/InvocationExportPluginCard.vue
index 17bf6078637..736457e9490 100644
--- a/client/src/components/Workflow/Invocation/Export/InvocationExportPluginCard.vue
+++ b/client/src/components/Workflow/Invocation/Export/InvocationExportPluginCard.vue
@@ -6,7 +6,7 @@ import ActionButton from "./ActionButton.vue";
 import StsDownloadButton from "components/StsDownloadButton.vue";
 import ExportToRemoteButton from "components/Workflow/Invocation/Export/ExportToRemoteButton.vue";
 import ExportToRemoteModal from "components/Workflow/Invocation/Export/ExportToRemoteModal.vue";
-import { useMarkdown } from "composables/useMarkdown";
+import { useMarkdown } from "composables/markdown";
 import { Toast } from "composables/toast";
 import axios from "axios";
 
diff --git a/client/src/composables/useConfig.js b/client/src/composables/config.js
similarity index 100%
rename from client/src/composables/useConfig.js
rename to client/src/composables/config.js
diff --git a/client/src/composables/useMarkdown.js b/client/src/composables/markdown.js
similarity index 100%
rename from client/src/composables/useMarkdown.js
rename to client/src/composables/markdown.js
diff --git a/client/src/composables/useMarkdown.test.js b/client/src/composables/markdown.test.js
similarity index 94%
rename from client/src/composables/useMarkdown.test.js
rename to client/src/composables/markdown.test.js
index fbb390313e1..aae29c6f59e 100644
--- a/client/src/composables/useMarkdown.test.js
+++ b/client/src/composables/markdown.test.js
@@ -1,4 +1,4 @@
-import { useMarkdown } from "composables/useMarkdown";
+import { useMarkdown } from "composables/markdown";
 
 describe("useMarkdown", () => {
     describe("renderMarkdown", () => {
diff --git a/client/src/composables/useTaskMonitor.js b/client/src/composables/taskMonitor.js
similarity index 100%
rename from client/src/composables/useTaskMonitor.js
rename to client/src/composables/taskMonitor.js
diff --git a/client/src/composables/useTaskMonitor.test.js b/client/src/composables/taskMonitor.test.js
similarity index 97%
rename from client/src/composables/useTaskMonitor.test.js
rename to client/src/composables/taskMonitor.test.js
index b8a5f13b04a..18eabadf983 100644
--- a/client/src/composables/useTaskMonitor.test.js
+++ b/client/src/composables/taskMonitor.test.js
@@ -1,7 +1,7 @@
 import axios from "axios";
 import MockAdapter from "axios-mock-adapter";
 import flushPromises from "flush-promises";
-import { useTaskMonitor } from "composables/useTaskMonitor";
+import { useTaskMonitor } from "composables/taskMonitor";
 
 const PENDING_TASK_ID = "pending-fake-task-id";
 const COMPLETED_TASK_ID = "completed-fake-task-id";

From 7e697b16d78b9d995ffad71f607b77ce2c517f4f Mon Sep 17 00:00:00 2001
From: Laila Los <44241786+ElectronicBlueberry@users.noreply.github.com>
Date: Thu, 17 Nov 2022 17:57:52 +0100
Subject: [PATCH 2/4] add composables documentation

---
 client/docs/composables.md             | 106 +++++++++++++++++++++++++
 client/docs/providers-and-renderers.md |  16 ++--
 2 files changed, 116 insertions(+), 6 deletions(-)
 create mode 100644 client/docs/composables.md

diff --git a/client/docs/composables.md b/client/docs/composables.md
new file mode 100644
index 00000000000..af133410444
--- /dev/null
+++ b/client/docs/composables.md
@@ -0,0 +1,106 @@
+# Composables
+
+Composables are way of splitting up your code into distinct, reusable chunks.
+They can replace providers, mixins and more. Any code you can put into a component, can also be written as a composable.
+Using them effectively can make your code more reusable, decoupled, and easier to follow.
+
+## Using Composables in the Composition API
+
+Example: accessing the current user from the store
+
+```vue
+<script setup>
+import { useCurrentUser } from "composables/user";
+
+const { currentUser } = useCurrentUser();
+</script>
+```
+
+You can now access the current user with `currentUser.value`.
+
+## Using Composables in the Options API
+
+Composables are not limited to the composition api. This is the same example from above, using the options api.
+
+```vue
+<script>
+import { useCurrentUser } from "composables/user";
+
+export default {
+    setup() {
+        const { currentUser } = useCurrentUser();
+        return { currentUser };
+    }
+}
+</script>
+```
+
+You can now access the current user with `this.currentUser` from anywhere within the component.
+
+## Testing Components with Composable Stores
+
+When writing a test which includes a component that has a composable store (like useCurrentUser),
+there are two ways to test it.
+
+### Mocking the store
+
+You can provide the store in the mount function as follows:
+
+```js
+const wrapper = shallowMount(TestedComponent,
+    localVue,
+    provide: { store },
+});
+```
+
+`store` must be a Vuex store.
+The `mockModule` helper can help creating a store for the required modules:
+
+```js
+const store = new Vuex.Store({
+    modules: {
+        user: mockModule(userStore),
+    },
+});
+```
+
+### Mocking the composable
+
+The second option is to mock the composable:
+
+```js
+import { useCurrentUser } from "composables/user";
+
+jest.mock("composables/user");
+useCurrentUser.mockReturnValue({
+    currentUser: {}
+});
+```
+
+While simpler in this example, you may need to manually mock more return values and composables than the other method, depending on the composables the component is using.
+
+## Using Composables for more than Stores
+
+Composables can be of great use to extract any reactive code from your components. For an example of this, take a look at [userFilterObjectArray](https://github.com/galaxyproject/galaxy/blob/dev/client/src/composables/utils/filter.js).
+
+Usage:
+
+```vue
+<script setup>
+import { useFilterObjectArray } from "composables/utils/filter";
+
+const filteredArray = useFilterObjectArray(
+    someReactiveArray,
+    searchValue,
+    ["name", "description"]
+);
+</script>
+```
+
+It's a simple filtering function, but fully reactive.
+Whenever any of the inputs changes, the return value is re-computed, without having to call the function again.
+
+## Further Reading
+
+* [Composition API](https://vuejs.org/api/composition-api-setup.html)
+* [\<script setup\>](https://vuejs.org/api/sfc-script-setup.html)
diff --git a/client/docs/providers-and-renderers.md b/client/docs/providers-and-renderers.md
index 447e6d74b74..ea25b36c62c 100644
--- a/client/docs/providers-and-renderers.md
+++ b/client/docs/providers-and-renderers.md
@@ -1,3 +1,7 @@
+**Notice** Consider using [Composables](composalbes.md) instead of Providers. They offer more functionality and need less boilerplate.
+
+---
+
 We are using components in two very distinct ways. The first, "normal", kind of component will
 probably look familiar to anybody whis is already passingly familiar with Vue. Here the relevant
 information comes in as properties, any internal variables get defined in "data", changes go out as
@@ -27,7 +31,7 @@ restriction that Vue needs a single root element in which to render.
 <template>
     <AutoComplete
         :options="options"
-        :value="doodad.category"  
+        :value="doodad.category"
         @select="saveCategory"
     />
 </template>
@@ -35,7 +39,7 @@ restriction that Vue needs a single root element in which to render.
 <script>
 
 export default {
-    props: { 
+    props: {
         doodad: { type: Object, required: true },
         options: { type: Array, required: true },
     },
@@ -51,7 +55,7 @@ export default {
 
 This component accepts a mandatory input object (doodad), lets the user play with a category prop,
 then emits a fresh object after it's done. So what, what's the big deal? The important part to walk
-away from this dumb example is the things that are NOT in this sample component. 
+away from this dumb example is the things that are NOT in this sample component.
 
 This component doesn't save the data. This component doesn't make ajax calls, and this component
 doesn't mutate its props. What it does do is to allow the user to edit some object named "doodad"
@@ -149,8 +153,8 @@ describe("A renderless component", () => {
             },
         });
 
-        // waits for "updated" Vue lifecycle hook to fire on the renderless 
-        // component. This is often good enough for waiting for 
+        // waits for "updated" Vue lifecycle hook to fire on the renderless
+        // component. This is often good enough for waiting for
         // an initial ajax load to finish, for example
         await waitForLifecyleEvent(wrapper.vm, "updated");
     })
@@ -161,4 +165,4 @@ describe("A renderless component", () => {
         // ...more tests
     })
 })
-```
\ No newline at end of file
+```

From 6e4a985d57d9f6993a60f673a6dcea2f694f7f43 Mon Sep 17 00:00:00 2001
From: Laila Los <44241786+ElectronicBlueberry@users.noreply.github.com>
Date: Thu, 17 Nov 2022 19:19:25 +0100
Subject: [PATCH 3/4] fix typo

Co-authored-by: Dannon <dannon.baker@gmail.com>
---
 client/docs/providers-and-renderers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/client/docs/providers-and-renderers.md b/client/docs/providers-and-renderers.md
index ea25b36c62c..480bef218ef 100644
--- a/client/docs/providers-and-renderers.md
+++ b/client/docs/providers-and-renderers.md
@@ -1,4 +1,4 @@
-**Notice** Consider using [Composables](composalbes.md) instead of Providers. They offer more functionality and need less boilerplate.
+**Notice** Consider using [Composables](composables.md) instead of Providers. They offer more functionality and need less boilerplate.
 
 ---
 

From ad98f36b3b0e9618d850c4416453e955e9f1c795 Mon Sep 17 00:00:00 2001
From: Laila Los <44241786+ElectronicBlueberry@users.noreply.github.com>
Date: Thu, 17 Nov 2022 19:28:42 +0100
Subject: [PATCH 4/4] add vue composable docs

move further reading to top
---
 client/docs/composables.md | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/client/docs/composables.md b/client/docs/composables.md
index af133410444..2ba75d898fc 100644
--- a/client/docs/composables.md
+++ b/client/docs/composables.md
@@ -4,6 +4,12 @@ Composables are way of splitting up your code into distinct, reusable chunks.
 They can replace providers, mixins and more. Any code you can put into a component, can also be written as a composable.
 Using them effectively can make your code more reusable, decoupled, and easier to follow.
 
+**More about Composables:**
+
+* [Composables Overview](https://vuejs.org/guide/reusability/composables.html)
+* [Composition API](https://vuejs.org/api/composition-api-setup.html)
+* [\<script setup\>](https://vuejs.org/api/sfc-script-setup.html)
+
 ## Using Composables in the Composition API
 
 Example: accessing the current user from the store
@@ -99,8 +105,3 @@ const filteredArray = useFilterObjectArray(
 
 It's a simple filtering function, but fully reactive.
 Whenever any of the inputs changes, the return value is re-computed, without having to call the function again.
-
-## Further Reading
-
-* [Composition API](https://vuejs.org/api/composition-api-setup.html)
-* [\<script setup\>](https://vuejs.org/api/sfc-script-setup.html)