@fishawack/lab-velocity 2.0.0-beta.5 → 2.0.0-beta.50

package/README.md

@@ -10,65 +10,496 @@ 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 & Admin files to work with the Hydrate Module including routes, store, axios and components.
+
+### Installation
+
+### Configure axios
+
+##### script.js
+
+```js
+import { Auth } from "@fishawack/lab-velocity";
+
+// Call in your boot method
+Auth.Axios.setAxiosDefaults(process.env.APP_URL, router);
+```
+
+### Configure router
+
+##### router.js
+
+```js
+import { Auth } from "@fishawack/lab-velocity";
+import store from "./store.js";
+
+// ... 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";
+
+[
+    // ... other routes
+
+    // End user routes for login, register, chang password etc
+    ...Auth.Router.routes(node),
+
+    // 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`,
+    }
+})
+```
+
+### Configure store
+
+##### store.js
+
+```js
+import { Auth } from "@fishawack/lab-velocity";
+
+// Call in store
+{
+    plugins: [
+        VuexPersistedState({
+            // ...
+            paths: ["auth.user"],
+        }),
+        Auth.ImpersonationPlugin,
+    ],
+
+    modules: {
+        auth: Auth.Store,
+    },
+
+    // ...
+}
+```
+
+`Auth.ImpersonationPlugin` displays a persistent banner when an admin is impersonating another user, persisted across page reloads.
+
+### Base Styles
+
+@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
 
-    Frontend files to to work with the Hydrate Module.
+##### vendor.scss
 
-#### Installation
+```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";
 
-##### Import Axios File
+// 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 "@fishawack/lab-velocity/components/descriptions";
+@import "@fishawack/lab-velocity/components/token-display";
+@import "element-plus/theme-chalk/el-tabs";
+@import "element-plus/theme-chalk/el-tab-pane";
+```
 
-    import axios from "axios";
-    import "@fishawack/lab-velocity/AuthModule/js/AuthAxios.js";
+Lastly for the admin layout & navigation import & apply the Layout component to the app.vue within your project.
 
-##### Import Routes File
+```vue
+<template>
+    <main id="app">
+        <VelLayout>
+            <router-view />
+        </VelLayout>
+    </main>
+</template>
 
-    Inside Router.js file
-    import { authRoutes, configureRoutes } from "@fishawack/lab-velocity/AuthModule/js/AuthRoutes";
+<script>
+import { Layout as VelLayout } from "@fishawack/lab-velocity";
+export default {
+    components: {
+        VelLayout,
+    },
+};
+</script>
+```
 
-    let routes = require("./routes.js")(null, store).concat(authRoutes(null,store,store.state.auth.authBase));
-    Add routes to createRouter call
+### Icons
 
-    add method call after createRouter
-    configureRoutes(router);
+Ensure Content has Velocity pulled in & copy out the svg folder contents into the svg files within vue.
+
+```json
+{
+    "aws-s3": "fishawack",
+    "location": "fw-auto-content/lab-velocity",
+    "key": "fw-s3-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"),
+];
+```
 
-##### Import Store
+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.
 
-    import AuthStore from "@fishawack/lab-velocity/AuthModule/js/AuthStore.js";
-    Inside createStore method add
-        modules: {
-            auth: AuthStore
+```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}`,
         },
-    Inside VuexPersistedState add
-        paths:["auth"]
+        properties,
+    );
+}
+```
+
+Layout is an array of functions that return render functions
+
+```js
+import { h, resolveComponent } from "vue";
 
-    At bottom of file set
-        window.store = store;
+{
+    // ...
+    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"),
+        ],
+    },
+}
+```
 
-##### SVGS
+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.
 
-    Ensure Content has Velocity pulled in
-    {
-        "lftp": "ftp-fishawack.egnyte.com",
-        "location": "Shared/FW/Knutsford/Digital/Auto-Content/Lab/Velocity"
+```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,
+            }
+        ]
     }
-    Copy out the svg folder contents into the svg files within vue.
+}
+```
+
+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
+                    }
+                }
+            ]
+        ),
+    },
+```
 
-##### ENV VARS
+## Local dev
 
-    HYDRATE_LOGO=example-logo
+To work locally mount a local clone of the project into the packages directory via an overridden docker compose file.
 
-    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)
+### Docker setup
 
-##### Verify dependencies are installed
+Create a docker compose file at `_Docker/docker-compose.yml`
 
-    Axios
-    form-backend-validation
+```yml
+services:
+    core:
+        volumes:
+            - $PWD/../lab-velocity:/app/packages/lab-velocity
+```
+
+### Npm install
+
+```bash
+npm install ./packages/lab-velocity
+```

package/_Build/js/libs/build-id.js

@@ -0,0 +1,14 @@
+if (process.env.NODE_ENV === "production") {
+    let uuid = document.documentElement.dataset.build;
+    let last = window.localStorage.getItem(`${process.env.REPO_NAME}-build-id`);
+
+    if (!last) {
+        console.log("no build detected - setting");
+        window.localStorage.clear();
+        window.localStorage.setItem(`${process.env.REPO_NAME}-build-id`, uuid);
+    } else if (uuid !== last) {
+        console.log("new build detected - resetting storage");
+        window.localStorage.clear();
+        window.localStorage.setItem(`${process.env.REPO_NAME}-build-id`, uuid);
+    }
+}

package/_Build/js/libs/filters.js

@@ -0,0 +1,36 @@
+import dayjs from "dayjs";
+import calendar from "dayjs/plugin/calendar";
+import localizedFormat from "dayjs/plugin/localizedFormat";
+import "dayjs/locale/en-gb";
+
+dayjs.extend(calendar);
+dayjs.extend(localizedFormat);
+dayjs.locale(navigator.language.toLowerCase());
+
+export function ucfirst(value) {
+    if (!value) return "";
+    value = value.toString();
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+export function calendarFormat(value) {
+    return !value
+        ? ""
+        : dayjs(value).calendar(null, {
+              sameElse: "DD/MM/YYYY",
+          });
+}
+
+export function dateFormat(value) {
+    return !value ? "" : dayjs(value).format("LLL");
+}
+
+export default {
+    install(Vue) {
+        Vue.config.globalProperties.$filters = {
+            ucfirst,
+            calendarFormat,
+            dateFormat,
+        };
+    },
+};

package/_Build/js/libs/globals.js

@@ -0,0 +1,7 @@
+import GSvg from "../../vue/modules/GSvg.vue";
+
+export default {
+    install(Vue) {
+        // Vue.component("GSvg", GSvg);
+    },
+};

package/_Build/js/libs/router.js

@@ -0,0 +1,22 @@
+import { createRouter, createWebHistory } from "vue-router";
+import { Auth } from "../../../index.js";
+
+const router = createRouter({
+    history: createWebHistory(),
+    linkExactActiveClass: "active",
+    base: process.env.BASE_URL,
+    routes: require("./routes.js")(),
+});
+
+router.beforeEach((to, from, next) => {
+    // Enforce routes have trailing forward slash
+    if (to.path.substr(-1) != "/") {
+        return next({ path: `${to.path}/`, query: to.query, hash: to.hash });
+    }
+
+    return next();
+});
+
+Auth.Router.beforeEach(router);
+
+export default router;

package/_Build/js/libs/routes.js

@@ -0,0 +1,29 @@
+"use strict";
+
+module.exports = (node) => [
+    {
+        path: "/",
+        component: node ? "" : require("../../vue/routes/PIndex.vue").default,
+        name: "index",
+        meta: {
+            guest: true,
+        },
+    },
+    {
+        path: "/404",
+        component: node ? "" : require("../../vue/routes/P404.vue").default,
+        meta: {
+            guest: true,
+        },
+    },
+    {
+        path: "/index.html",
+        redirect: "/",
+        prerender: false,
+    },
+    {
+        path: "/:pathMatch(.*)*",
+        redirect: "/404",
+        prerender: false,
+    },
+];

package/_Build/js/libs/store.js

@@ -0,0 +1,21 @@
+import { createStore } from "vuex";
+import VuexPersistedState from "vuex-persistedstate";
+import { Auth } from "../../../index.js";
+
+const store = createStore({
+    modules: {
+        auth: Auth.Store,
+    },
+    plugins: [
+        VuexPersistedState({
+            key: document.title,
+            paths: ["auth"],
+        }),
+    ],
+
+    state: {},
+
+    mutations: {},
+});
+
+export default store;