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

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,114 @@
+import { computed, ref, watch } from 'vue'
+import { useRoute } from 'vue-router'
+import { useTranslator } from '@userfrosting/sprinkle-core/stores'
+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()
+    const { translate } = useTranslator()
+
+    /**
+     * 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 = translate(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 ? translate(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/index.d.ts

@@ -0,0 +1,9 @@
+export {}
+
+declare module 'vue' {
+    interface ComponentCustomProperties {
+        // TODO : Use interface from sprinkle-core
+        $t: (key: string, placeholders?: string | number | object) => string
+        $tdate: (date: string, format?: string | object) => string
+    }
+}

package/app/assets/index.ts

@@ -1,8 +1,19 @@
-import { useConfigStore } from './stores'
+import type { App } from 'vue'
+import { useConfigStore, useTranslator } from './stores'
 
+/**
+ * Core Sprinkle initialization recipe.
+ *
+ * This recipe is responsible for loading the configuration from the api.
+ */
 export default {
-    install: () => {
-        const config = useConfigStore()
-        config.load()
+    install: (app: App) => {
+        useConfigStore().load()
+
+        // Load translations & add $t to global properties
+        const { translate, translateDate, load } = useTranslator()
+        load()
+        app.config.globalProperties.$t = translate
+        app.config.globalProperties.$tdate = translateDate
     }
 }

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/DictionaryApi.ts

@@ -0,0 +1,25 @@
+/**
+ * Api Interface - What the API expects and what it returns
+ *
+ * This interface is tied to the `DictionaryController` API, accessed at the
+ * GET `/api/dictionary` endpoint.
+ *
+ * This api doesn't have a corresponding Request data interface.
+ */
+export interface DictionaryResponse {
+    identifier: string
+    config: DictionaryConfig
+    dictionary: DictionaryEntries
+}
+
+export interface DictionaryEntries {
+    [key: string]: string
+}
+
+export interface DictionaryConfig {
+    name: string
+    regional: string
+    authors: string[]
+    plural_rule: number
+    dates: string
+}

package/app/assets/interfaces/index.ts

@@ -1,4 +1,30 @@
+/**
+ * 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'
+export type { DictionaryResponse, DictionaryEntries, DictionaryConfig } from './DictionaryApi'
+
+// 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/app/assets/stores/Helpers/PluralRules.ts

@@ -0,0 +1,218 @@
+/**
+ * Families: Asian (Chinese, Japanese, Korean, Vietnamese), Persian, Turkic/Altaic (Turkish), Thai, Lao
+ * 1 - everything: 0, 1, 2, ...
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export const rule0 = (number: number): number => {
+    return 1
+}
+
+/**
+ * Families: Germanic (Danish, Dutch, English, Faroese, Frisian, German, Norwegian, Swedish),
+ * Finno-Ugric (Estonian, Finnish, Hungarian), Language isolate (Basque),
+ * Latin/Greek (Greek), Semitic (Hebrew), Romanic (Italian, Portuguese, Spanish, Catalan)
+ * 1 - 1
+ * 2 - everything else: 0, 2, 3, ...
+ */
+export const rule1 = (number: number): number => {
+    return number === 1 ? 1 : 2
+}
+
+/**
+ * Families: Romanic (French, Brazilian Portuguese)
+ * 1 - 0, 1
+ * 2 - everything else: 2, 3, ...
+ */
+export const rule2 = (number: number): number => {
+    return number === 0 || number === 1 ? 1 : 2
+}
+
+/**
+ * Families: Baltic (Latvian)
+ * 1 - 0
+ * 2 - ends in 1, not 11: 1, 21, ... 101, 121, ...
+ * 3 - everything else: 2, 3, ... 10, 11, 12, ... 20, 22, ...
+ */
+export const rule3 = (number: number): number => {
+    return number === 0 ? 1 : number % 10 == 1 && number % 100 != 11 ? 2 : 3
+}
+
+/**
+ * Families: Celtic (Scottish Gaelic)
+ * 1 - is 1 or 11: 1, 11
+ * 2 - is 2 or 12: 2, 12
+ * 3 - others between 3 and 19: 3, 4, ... 10, 13, ... 18, 19
+ * 4 - everything else: 0, 20, 21, ...
+ */
+export const rule4 = (number: number): number => {
+    return number === 1 || number == 11
+        ? 1
+        : number === 2 || number === 12
+          ? 2
+          : number >= 3 && number <= 19
+            ? 3
+            : 4
+}
+
+/**
+ * Families: Romanic (Romanian)
+ * 1 - 1
+ * 2 - is 0 or ends in 01-19: 0, 2, 3, ... 19, 101, 102, ... 119, 201, ...
+ * 3 - everything else: 20, 21, ...
+ */
+export const rule5 = (number: number): number => {
+    return number === 1 ? 1 : number === 0 || (number % 100 > 0 && number % 100 < 20) ? 2 : 3
+}
+
+/**
+ * Families: Baltic (Lithuanian)
+ * 1 - ends in 1, not 11: 1, 21, 31, ... 101, 121, ...
+ * 2 - ends in 0 or ends in 10-20: 0, 10, 11, 12, ... 19, 20, 30, 40, ...
+ * 3 - everything else: 2, 3, ... 8, 9, 22, 23, ... 29, 32, 33, ...
+ */
+export const rule6 = (number: number): number => {
+    return number % 10 === 1 && number % 100 !== 11
+        ? 1
+        : number % 10 < 2 || (number % 100 >= 10 && number % 100 < 20)
+          ? 2
+          : 3
+}
+
+/**
+ * Families: Slavic (Croatian, Serbian, Russian, Ukrainian)
+ * 1 - ends in 1, not 11: 1, 21, 31, ... 101, 121, ...
+ * 2 - ends in 2-4, not 12-14: 2, 3, 4, 22, 23, 24, 32, ...
+ * 3 - everything else: 0, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 25, 26, ...
+ */
+export const rule7 = (number: number): number => {
+    return number % 10 === 1 && number % 100 !== 11
+        ? 1
+        : number % 10 >= 2 && number % 10 <= 4 && (number % 100 < 10 || number % 100 >= 20)
+          ? 2
+          : 3
+}
+
+/**
+ * Families: Slavic (Slovak, Czech)
+ * 1 - 1
+ * 2 - 2, 3, 4
+ * 3 - everything else: 0, 5, 6, 7, ...
+ */
+export const rule8 = (number: number): number => {
+    return number === 1 ? 1 : number >= 2 && number <= 4 ? 2 : 3
+}
+
+/**
+ * Families: Slavic (Polish)
+ * 1 - 1
+ * 2 - ends in 2-4, not 12-14: 2, 3, 4, 22, 23, 24, 32, ... 104, 122, ...
+ * 3 - everything else: 0, 5, 6, ... 11, 12, 13, 14, 15, ... 20, 21, 25, ...
+ */
+export const rule9 = (number: number): number => {
+    return number === 1
+        ? 1
+        : number % 10 >= 2 && number % 10 <= 4 && (number % 100 < 12 || number % 100 > 14)
+          ? 2
+          : 3
+}
+
+/**
+ * Families: Slavic (Slovenian, Sorbian)
+ * 1 - ends in 01: 1, 101, 201, ...
+ * 2 - ends in 02: 2, 102, 202, ...
+ * 3 - ends in 03-04: 3, 4, 103, 104, 203, 204, ...
+ * 4 - everything else: 0, 5, 6, 7, 8, 9, 10, 11, ...
+ */
+export const rule10 = (number: number): number => {
+    return number % 100 === 1
+        ? 1
+        : number % 100 === 2
+          ? 2
+          : number % 100 === 3 || number % 100 === 4
+            ? 3
+            : 4
+}
+
+/**
+ * Families: Celtic (Irish Gaeilge)
+ * 1 - 1
+ * 2 - 2
+ * 3 - is 3-6: 3, 4, 5, 6
+ * 4 - is 7-10: 7, 8, 9, 10
+ * 5 - everything else: 0, 11, 12, ...
+ */
+export const rule11 = (number: number): number => {
+    return number === 1
+        ? 1
+        : number === 2
+          ? 2
+          : number >= 3 && number <= 6
+            ? 3
+            : number >= 7 && number <= 10
+              ? 4
+              : 5
+}
+
+/**
+ * Families: Semitic (Arabic).
+ *
+ * 1 - 1
+ * 2 - 2
+ * 3 - ends in 03-10: 3, 4, ... 10, 103, 104, ... 110, 203, 204, ...
+ * 4 - ends in 11-99: 11, ... 99, 111, 112, ...
+ * 5 - everything else: 100, 101, 102, 200, 201, 202, ...
+ * 6 - 0
+ */
+export const rule12 = (number: number): number => {
+    return number === 1
+        ? 1
+        : number === 2
+          ? 2
+          : number % 100 >= 3 && number % 100 <= 10
+            ? 3
+            : number % 100 >= 11
+              ? 4
+              : number != 0
+                ? 5
+                : 6
+}
+
+/**
+ * Families: Semitic (Maltese)
+ * 1 - 1
+ * 2 - is 0 or ends in 01-10: 0, 2, 3, ... 9, 10, 101, 102, ...
+ * 3 - ends in 11-19: 11, 12, ... 18, 19, 111, 112, ...
+ * 4 - everything else: 20, 21, ...
+ */
+export const rule13 = (number: number): number => {
+    return number === 1
+        ? 1
+        : number === 0 || (number % 100 >= 1 && number % 100 < 11)
+          ? 2
+          : number % 100 > 10 && number % 100 < 20
+            ? 3
+            : 4
+}
+
+/**
+ * Families: Slavic (Macedonian)
+ * 1 - ends in 1: 1, 11, 21, ...
+ * 2 - ends in 2: 2, 12, 22, ...
+ * 3 - everything else: 0, 3, 4, ... 10, 13, 14, ... 20, 23, ...
+ */
+export const rule14 = (number: number): number => {
+    return number % 10 === 1 ? 1 : number % 10 === 2 ? 2 : 3
+}
+
+/**
+ * Families: Icelandic
+ * 1 - ends in 1, not 11: 1, 21, 31, ... 101, 121, 131, ...
+ * 2 - everything else: 0, 2, 3, ... 10, 11, 12, ... 20, 22, ...
+ */
+export const rule15 = (number: number): number => {
+    return number % 10 === 1 && number % 100 != 11 ? 1 : 2
+}
+
+export interface PluralRules {
+    [key: number]: (pluralValue: number) => number
+}

package/app/assets/stores/index.ts

@@ -1 +1,2 @@
 export { useConfigStore } from './config'
+export { useTranslator } from './useTranslator'