@userfrosting/sprinkle-core 6.0.0-alpha.1 → 6.0.0-alpha.2

package/app/assets/composables/index.ts

@@ -1 +1,2 @@
 export { useSprunjer } from './sprunjer'
+export { usePageMeta } from './usePageMeta'

package/app/assets/composables/sprunjer.ts

@@ -33,10 +33,10 @@
  */
 import { ref, toValue, watchEffect, computed } from 'vue'
 import axios from 'axios'
-import type { AssociativeArray, Sprunjer } from '../interfaces'
+import type { AssociativeArray, Sprunjer, SprunjerData, SprunjerResponse } from '../interfaces'
 
 export const useSprunjer = (
-    dataUrl: any,
+    dataUrl: string | (() => string),
     defaultSorts: AssociativeArray = {},
     defaultFilters: AssociativeArray = {},
     defaultSize: number = 10,
@@ -48,8 +48,15 @@ export const useSprunjer = (
     const sorts = ref<AssociativeArray>(defaultSorts)
     const filters = ref<AssociativeArray>(defaultFilters)
 
-    // Raw data
-    const data = ref<any>({})
+    // Raw data - Init with default data
+    const data = ref<SprunjerData>({
+        count: 0,
+        count_filtered: 0,
+        rows: [],
+        listable: {},
+        sortable: [],
+        filterable: []
+    })
 
     // State
     const loading = ref<boolean>(false)
@@ -60,7 +67,7 @@ export const useSprunjer = (
     async function fetch() {
         loading.value = true
         axios
-            .get(toValue(dataUrl), {
+            .get<SprunjerResponse>(toValue(dataUrl), {
                 params: {
                     size: size.value,
                     page: page.value,
@@ -69,13 +76,23 @@ export const useSprunjer = (
                 }
             })
             .then((response) => {
-                data.value = response.data
-                loading.value = false
+                // Assign the response data to the Sprunje Data.
+                // Note both object can't be assigned directly, as the response
+                // object is not a SprunjeData object.
+                data.value.count = response.data.count
+                data.value.count_filtered = response.data.count_filtered
+                data.value.rows = response.data.rows
+                data.value.listable = response.data.listable ?? {}
+                data.value.sortable = response.data.sortable ?? []
+                data.value.filterable = response.data.filterable ?? []
             })
             .catch((err) => {
                 // TODO : User toast alert, or export alert
                 console.error(err)
             })
+            .finally(() => {
+                loading.value = false
+            })
     }
 
     /**

package/app/assets/composables/usePageMeta.ts

@@ -0,0 +1,112 @@
+import { computed, ref, watch } from 'vue'
+import { useRoute } from 'vue-router'
+import { useConfigStore } from '../stores'
+import { defineStore } from 'pinia'
+
+/**
+ * Page Meta Composable
+ *
+ * Handles the page meta data such as title, description, plus generate
+ * breadcrumbs from the frontend router. The title, description and breadcrumbs
+ * are updated automatically when the route changes.
+ *
+ * Available States : breadcrumbs, title, description
+ */
+export const usePageMeta = defineStore('pageMeta', () => {
+    /**
+     * Globally provided properties
+     */
+    const route = useRoute()
+
+    /**
+     * States
+     *
+     * - title: The current page title
+     * - description: The current page description
+     * - breadcrumbs: The current page breadcrumbs
+     * - hideBreadcrumbs: Ask the component to hide the breadcrumbs on the page
+     * - hideTitle: Ask the component to hide the title on the page
+     */
+    const title = ref<string>('')
+    const description = ref<string>('')
+    const breadcrumbs = ref<Breadcrumb[]>([])
+    const hideBreadcrumbs = ref<boolean>(false)
+    const hideTitle = ref<boolean>(false)
+
+    /**
+     * Actions - Refresh the breadcrumbs, title and description
+     */
+    function refresh() {
+        // Reset default visibility attributes
+        hideBreadcrumbs.value = false
+        hideTitle.value = false
+
+        // Get route trail
+        const matchedRoutes = route.matched
+
+        // Filter to remove routes without title and assign values as defined
+        // in the breadcrumbs interface.
+        const crumbs = matchedRoutes
+            .filter(
+                (routeItem) => routeItem.meta.title !== undefined && routeItem.meta.title !== ''
+            )
+            .map((routeItem) => {
+                return {
+                    label: routeItem.meta?.title || '',
+                    to: routeItem.path
+                }
+            })
+
+        // Add site title as first breadcrumb
+        crumbs.unshift({
+            label: siteTitle.value,
+            to: '/'
+        })
+
+        // Replace ref with new values
+        breadcrumbs.value = crumbs
+
+        // Update Page Title & Description with current route
+        title.value = route.meta.title || ''
+        description.value = route.meta.description || ''
+    }
+
+    // Update the document title
+    function updatePageTitle() {
+        document.title = pageFullTitle.value
+    }
+
+    // Update the document description in the HTML meta tag
+    function updatePageDescription() {
+        const descriptionElement = document.querySelector('head meta[name="description"]')
+        descriptionElement?.setAttribute('content', description.value)
+    }
+
+    /**
+     * Computed Properties - Getters
+     *
+     * - siteTitle: Return the site title from the config Store
+     * - pageFullTitle: Return the full page title
+     */
+    const siteTitle = computed<string>(() => useConfigStore().get('site.title') || '')
+    const pageFullTitle = computed<string>(() => {
+        return title.value ? title.value + ' | ' + siteTitle.value : siteTitle.value
+    })
+
+    /**
+     * Watchers - route, page title and description changes
+     */
+    watch(route, refresh, { immediate: true })
+    watch(pageFullTitle, updatePageTitle, { immediate: true })
+    watch(description, updatePageDescription, { immediate: true })
+
+    /**
+     * Returns the states and actions
+     */
+    return { breadcrumbs, title, description, hideBreadcrumbs, hideTitle }
+})
+
+interface Breadcrumb {
+    label: string
+    to: string
+}

package/app/assets/interfaces/ApiResponse.ts

@@ -0,0 +1,8 @@
+/**
+ * Interfaces - What the API expects and what it returns
+ *
+ * Generic API Response interface.
+ */
+export interface ApiResponse {
+    message: string
+}

package/app/assets/interfaces/index.ts

@@ -1,4 +1,29 @@
+/**
+ * Interface for custom routes meta fields.
+ *
+ * Meta Fields Added :
+ * - title: string - Page title
+ * - description: string - Page description
+ *
+ * Theses fields are used to set the document title and description, as well as
+ * for breadcrumbs generation.
+ *
+ * @see https://router.vuejs.org/guide/advanced/meta.html#TypeScript
+ */
+import 'vue-router'
+
+declare module 'vue-router' {
+    interface RouteMeta {
+        title?: string
+        description?: string
+    }
+}
+
 export type { AlertInterface } from './alerts'
 export type { AssociativeArray } from './common'
 export { Severity } from './severity'
-export type { Sprunjer } from './sprunjer'
+export type { Sprunjer, SprunjerData, SprunjerListable, SprunjerListableOption } from './sprunjer'
+export type { SprunjerRequest, SprunjerResponse } from './sprunjerApi'
+
+// Misc
+export type { ApiResponse } from './ApiResponse'

package/app/assets/interfaces/sprunjer.ts

@@ -7,12 +7,12 @@ import type { Ref, ComputedRef } from 'vue'
 import type { AssociativeArray } from '.'
 
 export interface Sprunjer {
-    dataUrl: any
+    dataUrl: string | (() => string)
     size: Ref<number>
     page: Ref<number>
     sorts: Ref<AssociativeArray>
     filters: Ref<AssociativeArray>
-    data: Ref<any>
+    data: Ref<SprunjerData>
     fetch: () => void
     loading: Ref<boolean>
     totalPages: ComputedRef<number>
@@ -24,3 +24,36 @@ export interface Sprunjer {
     last: ComputedRef<number>
     toggleSort: (column: string) => void
 }
+
+/**
+ * Sprunjer Data. Represents the data that is returned from any Sprunjer
+ * Composable. It is different than SprunjerResponse, as the response if what
+ * the API return, Data is what Vue provides. Both are similar, but Data doesn't
+ * have optional values.
+ *
+ * N.B.: "rows" uses a generic array. It can contain any object, and should
+ * actually be can be extended for each Sprunjer
+ */
+export interface SprunjerData {
+    count: number
+    count_filtered: number
+    rows: any[]
+    listable: SprunjerListable
+    sortable: string[]
+    filterable: string[]
+}
+
+/**
+ * Sprunjer Listable. Represents a listable for a Sprunjer.
+ */
+export interface SprunjerListable {
+    [key: string]: SprunjerListableOption[]
+}
+
+/**
+ * Sprunjer Listable Option. Represents a listable option for a Sprunjer.
+ */
+export interface SprunjerListableOption {
+    value: string
+    text: string
+}

package/app/assets/interfaces/sprunjerApi.ts

@@ -0,0 +1,33 @@
+import type { AssociativeArray, SprunjerListable } from '.'
+
+/**
+ * Sprunje API Interfaces - What the API expects and what it returns.
+ */
+
+/**
+ * Sprunjer Response. All the data that is returned from any Sprunjer API.
+ * Note listable, sortable and filterable are optional when dealing with the API.
+ *
+ * N.B.: "rows" uses a generic array. It can contain any object, and should
+ * actually be can be extended for each Sprunjer
+ */
+export interface SprunjerResponse {
+    count: number
+    count_filtered: number
+    rows: any[]
+    listable?: SprunjerListable
+    sortable?: string[]
+    filterable?: string[]
+}
+
+/**
+ * Sprunjer Request. All the parameters that can be passed to a Sprunjer.
+ * All parameters are optional.
+ */
+export interface SprunjerRequest {
+    size?: number
+    page?: number
+    sorts?: AssociativeArray
+    filters?: AssociativeArray
+    format?: string
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@userfrosting/sprinkle-core",
-    "version": "6.0.0-alpha.1",
+    "version": "6.0.0-alpha.2",
     "type": "module",
     "description": "Core Sprinkle for UserFrosting",
     "funding": "https://opencollective.com/userfrosting",