@fishawack/lab-velocity 2.0.0-beta.3 → 2.0.0-beta.30

package/README.md

@@ -10,65 +10,469 @@ Prevent code repetition.
 
 ## Getting started
 
+### Requirements
+
+```json
+"vue": "^3.3.4",
+"vue-router": "^4.2.4",
+"vuex": "^4.1.0",
+"vuex-persistedstate": "^4.1.0"
+"vue-loader": "^17.2.2"
+```
+
 ### Install
 
 ```bash
 npm install @fishawack/lab-velocity
 ```
 
-### Auth Module
+## Hydrate Views
 
-    Frontend files to to work with the Hydrate Module.
+Frontend & Admin files to work with the Hydrate Module including routes, store, axios and components.
 
-#### Installation
+### Installation
 
-##### Import Axios File
+### Configure axios
 
-    import axios from "axios";
-    import "@fishawack/lab-velocity/AuthModule/js/AuthAxios.js";
+##### script.js
 
-##### Import Routes File
+```js
+import { Auth } from "@fishawack/lab-velocity";
 
-    Inside Router.js file
-    import { authRoutes, configureRoutes } from "@fishawack/lab-velocity/AuthModule/js/AuthRoutes";
+// Call in your boot method
+Auth.Axios.setAxiosDefaults(process.env.APP_URL, router);
+```
 
-    let routes = require("./routes.js")(null, store).concat(authRoutes(null,store,store.state.auth.authBase));
-    Add routes to createRouter call
+### Configure router
 
-    add method call after createRouter
-    configureRoutes(router);
+##### router.js
 
-##### Import Store
+```js
+import { Auth } from "@fishawack/lab-velocity";
+import store from "./store.js";
 
-    import AuthStore from "@fishawack/lab-velocity/AuthModule/js/AuthStore.js";
-    Inside createStore method add
-        modules: {
-            auth: AuthStore
-        },
-    Inside VuexPersistedState add
-        paths:["auth"]
+// ... initialize router
+
+Auth.Router.beforeEach(router, store);
+```
+
+### Configure routes
+
+There are two different set of routes for the admin and the frontend.
+
+##### routes.js
+
+```js
+import { Auth } from "@fishawack/lab-velocity";
 
-    At bottom of file set
-        window.store = store;
+[
+    // ... other routes
 
-##### SVGS
+    // End user routes for login, register, chang password etc
+    ...Auth.Router.routes(node),
 
-    Ensure Content has Velocity pulled in
-    {
-        "lftp": "ftp-fishawack.egnyte.com",
-        "location": "Shared/FW/Knutsford/Digital/Auto-Content/Lab/Velocity"
+    // Admin routes for headless login & managing users & companies
+    ...Auth.Router.adminRoutes(node),
+
+    // ... wildcard 404 routes etc
+];
+```
+
+You can override the default setup for companies & user resources by passing an optional second object to the `adminRoutes` method. See the [resources](#Resources) section below for available options.
+
+```js
+...Auth.Router.adminRoutes(node, {
+    userResource: {
+        label: "Custom User label",
+        api: `/api/v2/users`,
     }
-    Copy out the svg folder contents into the svg files within vue.
+})
+```
 
-##### ENV VARS
+### Configure store
 
-    HYDRATE_LOGO=example-logo
+##### store.js
+
+```js
+import { Auth } from "@fishawack/lab-velocity";
+
+// Call in store
+{
+    plugins: [
+        VuexPersistedState({
+            // ...
+            paths: ["auth.user"],
+        }),
+    ],
+
+    modules: {
+        auth: Auth.Store,
+    },
+
+    // ...
+}
+```
 
-    HYDRATE_LOGO=example-logo(No Default set, name of svg logo to display on page)
-    HYDRATE_REDIRECT=(Default index if not configured)
-    HYDRATE_CONTACT=(Default mailto:EP@avalerehealth, Email for contact us button)
+### Base Styles
 
-##### Verify dependencies are installed
+@fishawack/lab-velocity extends @fishawack/lab-ui, for this reason you should replace the two references to variables & defaults with @fishawack/lab-velocity ones.
+
+#### \_variables.scss
+
+```sass
+@import "@fishawack/lab-velocity/variables";
+
+// Set global variables here, e.g $color6: red;
+```
+
+#### \_defaults.scss
+
+```sass
+@use "variables";
+@import "@fishawack/lab-velocity/defaults";
+
+$colors: variables.dynamic("color", module-variables("variables"));
+
+// Override lab-ui defaults here, e.g $button: $color6;
+```
+
+### Route Styles
+
+There are two different set of sass imports for the admin and the frontend routes.
+
+#### Frontend
+
+```sass
+// Vendor imports / Lab-ui imports
+@import "@fishawack/lab-ui/typography";
+@import "@fishawack/lab-ui/grid";
+@import "@fishawack/lab-ui/utilities";
+@import "@fishawack/lab-ui/icon";
+
+// Lab velocity
+@import "@fishawack/lab-velocity/base";
+@import "@fishawack/lab-velocity/components/basic";
+@import "@fishawack/lab-velocity/components/button";
+@import "@fishawack/lab-velocity/components/form";
+@import "@fishawack/lab-velocity/components/auth";
+```
+
+#### Admin
+
+##### vendor.scss
+
+```sass
+// Vendor imports / Lab-ui imports
+@import "@fishawack/lab-ui/typography";
+@import "@fishawack/lab-ui/grid";
+@import "@fishawack/lab-ui/utilities";
+@import "@fishawack/lab-ui/icon";
+
+// Lab velocity
+@import "@fishawack/lab-velocity/base";
+@import "@fishawack/lab-velocity/components/pageTitle";
+@import "@fishawack/lab-velocity/components/breadcrumbs";
+@import "@fishawack/lab-velocity/components/table";
+@import "@fishawack/lab-velocity/components/icon";
+@import "@fishawack/lab-velocity/components/basic";
+@import "@fishawack/lab-velocity/components/button";
+@import "@fishawack/lab-velocity/components/form";
+@import "@fishawack/lab-velocity/components/checkbox";
+@import "@fishawack/lab-velocity/components/select";
+@import "@fishawack/lab-velocity/components/loader";
+@import "@fishawack/lab-velocity/components/permissionLegend";
+@import "@fishawack/lab-velocity/components/chip";
+@import "@fishawack/lab-velocity/components/header";
+@import "@fishawack/lab-velocity/components/footer";
+@import "@fishawack/lab-velocity/components/sidebar";
+@import "@fishawack/lab-velocity/components/menu";
+@import "@fishawack/lab-velocity/components/layout";
+@import "element-plus/theme-chalk/el-tabs";
+@import "element-plus/theme-chalk/el-tab-pane";
+```
 
-    Axios
-    form-backend-validation
+Lastly for the admin layout & navigation import & apply the Layout component to the app.vue within your project.
+
+```vue
+<template>
+    <main id="app">
+        <VelLayout>
+            <router-view />
+        </VelLayout>
+    </main>
+</template>
+
+<script>
+import { Layout as VelLayout } from "@fishawack/lab-velocity";
+export default {
+    components: {
+        VelLayout,
+    },
+};
+</script>
+```
+
+### Icons
+
+Ensure Content has Velocity pulled in & copy out the svg folder contents into the svg files within vue.
+
+```json
+{
+    "lftp": "ftp-fishawack.egnyte.com",
+    "location": "Shared/FW/Knutsford/Digital/Auto-Content/Lab/Velocity"
+}
+```
+
+### ENV VARS (frontend)
+
+```env
+# Descriptions
+HYDRATE_LOGO Name of primary logo (default: example-logo)
+HYDRATE_LOGO_REVERSE Name of the logo when color scheme is reversed (default: to HYDRATE_LOGO value if not provided)
+HYDRATE_REDIRECT Name of the route name to redirect to after login (default: index)
+HYDRATE_CONTACT Email for contact us button (default: mailto:det@avalerehealth.com)
+```
+
+## Resources
+
+To reduce the amount of template code needed you can import a fairly standard set of route files for index, show, create, edit & form via the resource module.
+
+##### routes.js
+
+```js
+import { Resource } from "@fishawack/lab-velocity";
+
+[
+    // ... other routes
+    ...Resource.routes(node, "posts"),
+];
+```
+
+A third optional object can be passed for meta data that contains all of the overrides to customize the full rendering of these resource files. The default meta object is below.
+
+```js
+// Name is the first param, properties is the optional second param
+export function meta(name, properties = {}) {
+    const singular = properties.singular || name.slice(0, -1);
+
+    return merge(
+        {
+            name,
+            title: properties.title || name[0].toUpperCase() + name.slice(1),
+            singular,
+            label: singular,
+            multiLabel: name,
+            pageLink: name,
+            api: `/api/${name}`,
+            permissions: {
+                create: () => true,
+                edit: () => true,
+            },
+            searchable: {
+                value: "name",
+                label: `Search ${name}`,
+            },
+            form: {
+                component: null,
+                fields: () => ({}),
+            },
+            table: {
+                structure: [
+                    {
+                        key: "id",
+                    },
+                ],
+            },
+            description: {
+                structure: [
+                    {
+                        key: "id",
+                    },
+                ],
+            },
+            index: {
+                actions: [],
+                layout: [
+                    (props) => {
+                        const { resource } = props;
+
+                        return h(VTableSorter, {
+                            key: "PIndex",
+                            "json-data": {
+                                ...resource,
+                                tableStructure: resource.table.structure,
+                            },
+                            defaults: resource.defaults,
+                            "fixed-height": false,
+                            "display-edit-action":
+                                resource.permissions.create(props),
+                        });
+                    },
+                ],
+            },
+            show: {
+                actions: [],
+                layout: [
+                    (props) => {
+                        const { resource, model } = props;
+
+                        return h(
+                            ElDescriptions,
+                            {
+                                border: true,
+                                column: 1,
+                            },
+                            resource.description.structure.map((item, index) =>
+                                h(
+                                    ElDescriptionsItem,
+                                    {
+                                        key: index,
+                                        labelWidth: "20%",
+                                    },
+                                    {
+                                        label: () =>
+                                            item.label ||
+                                            item.key[0].toUpperCase() +
+                                                item.key.slice(1),
+                                        default: () =>
+                                            item.render
+                                                ? h(item.render(props))
+                                                : model?.[item.key] || "",
+                                    },
+                                ),
+                            ),
+                        );
+                    },
+                ],
+            },
+            defaults: "",
+            icon: `icon-${singular}`,
+        },
+        properties,
+    );
+}
+```
+
+Layout is an array of functions that return render functions
+
+```js
+import { h, resolveComponent } from "vue";
+
+{
+    // ...
+    show: {
+        layout: [
+            ({ model }) =>
+                h(resolveComponent("router-link"), {
+                    class: "underline",
+                    to: {
+                        name: "companies.show",
+                        params: { id: model.company_id },
+                    },
+                    text: model.company.name,
+                })
+        ],
+    },
+}
+```
+
+You can see above that the show & index route have a default render function returned for a table and description block. If you want to keep this you can grab the existing render function from the `defaultResource` export.
+
+```js
+import { defaultResource, meta } from "../../../resource/index.js";
+
+{
+    // ...
+    index: {
+        layout: [
+            () => h("div", "I appear above"),
+            ...defaultResource.index.layout,
+            () => h("div", "I appear below"),
+        ],
+    },
+}
+```
+
+Structure arrays take objects. The objects require a key only but have other optional properties. A render function can also be passed to fully customize the rendering that happens.
+
+```js
+{
+    table: {
+        structure: [
+            {
+                key: "name",
+                sortable: true,
+            },
+            {
+                key: "role",
+                render: () => h("div", "Custom template"),
+            },
+        ],
+    },
+    form: {
+        structure: [
+            {
+                key: "name",
+            },
+            {
+                key: "provider_name",
+                label: "Provider",
+                render: ({ model }) => h("span", model?.provider_name.label ?? ""),
+                initial: ({ model }) => model?.provider_name.value ?? null,
+            }
+        ]
+    }
+}
+```
+
+Generally speaking the only different between admin routes tends to do the columns which within a model are shared. Because of this you can use the utility method `columns` to automatically build out the table, description & form fields using the following syntax.
+
+```js
+import { Resource } from "@fishawack/lab-velocity";
+import { Checkbox as VelCheckbox } from "@fishawack/lab-velocity";
+
+{
+        api: `/api/posts`,
+        icon: `icon-visibility`,
+        permissions: {
+            create: ({ $store }) => $store.getters.can("write personas"),
+            edit: ({ $store }) => $store.getters.can("write personas"),
+        },
+        ...Resource.columns(
+            [
+                {
+                    key: "name",
+                    sortable: true,
+                },
+                {
+                    key: "description",
+                },
+                {
+                    key: "is_experimental",
+                    label: "Experimental",
+                    render: {
+                        write: () => h(VelCheckbox),
+                    },
+                    initial: ({ model }) => model?.is_experimental ?? false,
+                },
+                {
+                    key: "nested",
+                    label: "Nested",
+                    render: {
+                        read: ({ model }) =>
+                            h("span", model?.nested.name ?? ""),
+                    },
+                    initial: ({ model }) =>
+                        model?.nested.id ?? null,
+                },
+                {
+                    key: "client_id",
+                    label: "Client id",
+                    filter: {
+                        form: true
+                    }
+                }
+            ]
+        ),
+    },
+```

package/_Build/vue/components/basic/Button.vue

@@ -34,7 +34,7 @@ export default {
         },
         type: {
             type: String,
-            default: null,
+            default: "default",
         },
         name: {
             type: String,

package/_Build/vue/components/form/Select.vue

@@ -56,8 +56,8 @@ export default {
     props: {
         ...input.props,
         modelValue: {
-            type: Array,
-            default: [],
+            type: [Array, Number],
+            default: () => [],
         },
         baseClass: {
             type: String,

package/_Build/vue/components/form/Spinner.vue

@@ -0,0 +1,5 @@
+<template>
+    <p>Loading...</p>
+</template>
+
+<script></script>

package/_Build/vue/components/layout/Alert.vue

@@ -11,7 +11,11 @@
 <script>
 import { ElAlert } from "element-plus";
 export default {
-    name: "VPageTitle",
+    name: "Alert",
+
+    components: {
+        ElAlert,
+    },
 
     props: {
         effect: {
@@ -30,9 +34,5 @@ export default {
             default: true,
         },
     },
-
-    components: {
-        ElAlert,
-    },
 };
 </script>

package/_Build/vue/{modules/AuthModule/components/VBreadcrumbs.vue → components/layout/Breadcrumbs.vue}

@@ -3,7 +3,7 @@
         <div class="container px-6 tablet:px-4 mobile:px-2 mb-8 ml-0 mr-0">
             <div class="grid__1/1">
                 <div class="flex items-center">
-                    <breadcrumbs :crumbs="items" />
+                    <VelBreadcrumbs :crumbs="items" />
                 </div>
             </div>
         </div>
@@ -11,12 +11,12 @@
 </template>
 
 <script>
-import Breadcrumbs from "../../../components/navigation/Breadcrumbs.vue";
+import VelBreadcrumbs from "../navigation/Breadcrumbs.vue";
 
 export default {
-    name: "VBreadcrumbs",
+    name: "Breadcrumbs",
     components: {
-        Breadcrumbs,
+        VelBreadcrumbs,
     },
 
     props: {

package/_Build/vue/{modules/AuthModule/components → components/layout}/Chips.vue

@@ -1,7 +1,7 @@
 <template>
     <div class="chips">
         <template v-for="(item, index) in array" :key="item.name">
-            <Chip
+            <VelChip
                 class="chip--round"
                 :name="item.name"
                 :label="`${item.label}${index < array.length - 1 ? ',' : ''}`"
@@ -13,7 +13,7 @@
 <script>
 export default {
     components: {
-        Chip: require("./Chip.vue").default,
+        VelChip: require("./Chip.vue").default,
     },
 
     props: {

package/_Build/vue/components/layout/Footer.vue

@@ -8,25 +8,25 @@
         <div class="vel-footer__bottom">
             <div class="vel-footer__bottom__links">
                 <p class="color-0">&copy;2025 Avalere Health.</p>
-                <el-link
+                <VelLink
                     underline
                     class="color-0 ml"
                     href="https://avalerehealth.com/privacy-policy/"
                     target="_blank"
-                    >Privacy Policy</el-link
+                    >Privacy Policy</VelLink
                 >
-                <el-link
+                <VelLink
                     underline
                     class="color-0 ml"
                     href="https://avalerehealth.com/corporate-policies/"
                     target="_blank"
-                    >Corporate policies and compliance</el-link
+                    >Corporate policies and compliance</VelLink
                 >
             </div>
             <div class="vel-footer__bottom__end">
                 <p class="color-0">Have a question?</p>
-                <el-link underline class="color-0 ml" :href="contact"
-                    >Contact our Support Team</el-link
+                <VelLink underline class="color-0 ml" :href="contact"
+                    >Contact our Support Team</VelLink
                 >
             </div>
         </div>
@@ -34,17 +34,18 @@
 </template>
 
 <script>
-import elLink from "../basic/link.vue";
+import VelLink from "../basic/link.vue";
 
 export default {
+    components: {
+        VelLink,
+    },
+
     props: {
         contact: {
             required: true,
             type: String,
         },
     },
-    components: {
-        elLink,
-    },
 };
 </script>