@userfrosting/sprinkle-core 6.0.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2013-2024 Alexander Weissman & Louis Charette
+
+UserFrosting is 100% free and open-source.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# UserFrosting 5.2 Core Sprinkle
+
+[![Version](https://img.shields.io/github/v/release/userfrosting/sprinkle-core?include_prereleases)](https://github.com/userfrosting/sprinkle-core/releases)
+![PHP Version](https://img.shields.io/badge/php-%5E8.1-brightgreen)
+[![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)](LICENSE.md)
+[![Build](https://img.shields.io/github/actions/workflow/status/userfrosting/sprinkle-core/Build.yml?branch=5.2&logo=github)](https://github.com/userfrosting/sprinkle-core/actions)
+[![Codecov](https://codecov.io/gh/userfrosting/sprinkle-core/branch/5.2/graph/badge.svg)](https://app.codecov.io/gh/userfrosting/sprinkle-core/branch/5.2)
+[![StyleCI](https://github.styleci.io/repos/372359383/shield?branch=5.2&style=flat)](https://github.styleci.io/repos/372359383)
+[![PHPStan](https://img.shields.io/github/actions/workflow/status/userfrosting/sprinkle-core/PHPStan.yml?branch=5.2&label=PHPStan)](https://github.com/userfrosting/sprinkle-core/actions/workflows/PHPStan.yml)
+[![Join the chat](https://img.shields.io/badge/Chat-UserFrosting-brightgreen?logo=Rocket.Chat)](https://chat.userfrosting.com)
+[![Donate](https://img.shields.io/badge/Open_Collective-Donate-blue?logo=Open%20Collective)](https://opencollective.com/userfrosting#backer)
+[![Donate](https://img.shields.io/badge/Ko--fi-Donate-blue?logo=ko-fi&logoColor=white)](https://ko-fi.com/lcharette)
+
+## By [Alex Weissman](https://alexanderweissman.com) and [Louis Charette](https://bbqsoftwares.com)
+
+Copyright (c) 2013-2024, free to use in personal and commercial software as per the [license](LICENSE.md).
+
+UserFrosting is a secure, modern user management system written in PHP and built on top of the [Slim Microframework](http://www.slimframework.com/), [Twig](http://twig.sensiolabs.org/) templating engine, and [Eloquent](https://laravel.com/docs/10.x/eloquent#introduction) ORM.
+
+This **Core Sprinkle** provides most of the "heavy lifting" PHP code. It provides all the necessary services for database, templating, error handling, mail support, request throttling, and more.
+
+## Installation in your UserFrosting project
+To use this sprinkle in your UserFrosting project, follow theses instructions (*N.B.: This sprinkle is enabled by default when using the base app template*).
+
+1. Require in your [UserFrosting](https://github.com/userfrosting/UserFrosting) project : 
+    ```
+    composer require userfrosting/sprinkle-core
+    ```
+
+2. Add the Sprinkle to your Sprinkle Recipe : 
+    ```php
+    public function getSprinkles(): array
+    {
+        return [
+            \UserFrosting\Sprinkle\Core\Core::class,
+        ];
+    }
+    ```
+
+3. Bake
+    ```bash
+    php bakery bake
+    ```
+
+## Install locally and run tests
+You can also install this sprinkle locally. This can be useful to debug or contribute to this sprinkle. 
+
+1. Clone repo :
+    ```
+    git clone https://github.com/userfrosting/sprinkle-core.git
+    ```
+2. Change directory
+    ```
+    cd sprinkle-core
+    ```
+3. Install dependencies :
+    ```
+    composer install
+    ```
+4. Run bake command :
+    ```
+    php bakery bake
+    ```
+
+From this point, you can use the same command as with any other sprinkle. 
+
+Tests can be run using the bundled PHPUnit :
+```
+vendor/bin/phpunit
+```
+
+Same for PHPStan, for code quality :
+```
+vendor/bin/phpstan analyse app/src/
+```
+
+## Documentation
+See main [UserFrosting Documentation](https://learn.userfrosting.com) for more information.
+
+- [Changelog](CHANGELOG.md)
+- [Issues](https://github.com/userfrosting/UserFrosting/issues)
+- [License](LICENSE.md)
+- [Style Guide](https://github.com/userfrosting/.github/blob/main/.github/STYLE-GUIDE.md)
+
+## Contributing
+
+This project exists thanks to all the people who contribute. If you're interested in contributing to the UserFrosting codebase, please see our [contributing guidelines](https://github.com/userfrosting/UserFrosting/blob/5.2/.github/CONTRIBUTING.md) as well as our [style guidelines](.github/STYLE-GUIDE.md).
+
+[![](https://opencollective.com/userfrosting/contributors.svg?width=890&button=true)](https://github.com/userfrosting/sprinkle-core/graphs/contributors)

package/app/assets/composables/index.ts

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

package/app/assets/composables/sprunjer.ts

@@ -0,0 +1,164 @@
+/**
+ * Sprunjer Composable
+ *
+ * A composable function that fetches data from a Sprunjer API and provides
+ * all necessary function like pagination, sorting and filtering.
+ *
+ * Pass the URL of the Sprunjer API to the function, and it will fetch the data.
+ * A watcher will refetch the data whenever any parameters change.
+ *
+ * Params:
+ * @param {String} dataUrl - The URL of the Sprunjer API
+ * @param {Object} defaultSorts - An object of default sorts
+ * @param {Object} defaultFilters - An object of default filters
+ * @param {Number} defaultSize - The default number of items per page
+ * @param {Number} defaultPage - The default page number
+ *
+ * Exports:
+ * - size: The number of items per page
+ * - page: The current page number
+ * - sorts: An object of sorts
+ * - filters: An object of filters
+ * - data: The raw data from the API
+ * - fetch: A function to fetch the data
+ * - loading: A boolean indicating if the data is loading
+ * - totalPages: The total number of pages
+ * - downloadCsv: A function to download the data as a CSV file
+ * - countFiltered: The total number of items after filtering
+ * - count: The total number of items
+ * - rows: The rows of data
+ * - first: The index of the first item on the current page
+ * - last: The index of the last item on the current page
+ * - toggleSort: A function to toggle the sort order of a column
+ */
+import { ref, toValue, watchEffect, computed } from 'vue'
+import axios from 'axios'
+import type { AssociativeArray, Sprunjer } from '../interfaces'
+
+export const useSprunjer = (
+    dataUrl: any,
+    defaultSorts: AssociativeArray = {},
+    defaultFilters: AssociativeArray = {},
+    defaultSize: number = 10,
+    defaultPage: number = 0
+): Sprunjer => {
+    // Sprunje parameters
+    const size = ref<number>(defaultSize)
+    const page = ref<number>(defaultPage)
+    const sorts = ref<AssociativeArray>(defaultSorts)
+    const filters = ref<AssociativeArray>(defaultFilters)
+
+    // Raw data
+    const data = ref<any>({})
+
+    // State
+    const loading = ref<boolean>(false)
+
+    /**
+     * Api fetch function
+     */
+    async function fetch() {
+        loading.value = true
+        axios
+            .get(toValue(dataUrl), {
+                params: {
+                    size: size.value,
+                    page: page.value,
+                    sorts: sorts.value,
+                    filters: filters.value
+                }
+            })
+            .then((response) => {
+                data.value = response.data
+                loading.value = false
+            })
+            .catch((err) => {
+                // TODO : User toast alert, or export alert
+                console.error(err)
+            })
+    }
+
+    /**
+     * Computed properties
+     */
+    const totalPages = computed(() => {
+        // N.B.: Sprunjer page starts at 0, not 1
+        // Make sure page is never negative
+        return Math.max(Math.ceil((data.value.count_filtered ?? 0) / size.value) - 1, 0)
+    })
+
+    const count = computed(() => {
+        return data.value.count ?? 0
+    })
+
+    const first = computed(() => {
+        return Math.min(page.value * size.value + 1, data.value.count ?? 0)
+    })
+
+    const last = computed(() => {
+        return Math.min((page.value + 1) * size.value, data.value.count_filtered ?? 0)
+    })
+
+    const countFiltered = computed(() => {
+        return data.value.count_filtered ?? 0
+    })
+
+    const rows = computed(() => {
+        return data.value.rows ?? []
+    })
+
+    /**
+     * Download the data as a CSV file
+     */
+    function downloadCsv() {
+        console.log('Not yet implemented')
+    }
+
+    /**
+     * Apply sorting to a column, cycling from the previous sort order.
+     * Order goes : asc -> desc -> null -> asc
+     * Used to toggle the sort order of a column when the column header is clicked
+     * @param column The column to sort
+     */
+    function toggleSort(column: string) {
+        let newOrder: string | null
+        if (sorts.value[column] === 'asc') {
+            newOrder = 'desc'
+        } else if (sorts.value[column] === 'desc') {
+            newOrder = null
+        } else {
+            newOrder = 'asc'
+        }
+
+        sorts.value[column] = newOrder
+    }
+
+    /**
+     * Automatically fetch the data when any parameters change
+     */
+    watchEffect(() => {
+        fetch()
+    })
+
+    /**
+     * Export the functions and data
+     */
+    return {
+        dataUrl,
+        size,
+        page,
+        sorts,
+        filters,
+        data,
+        fetch,
+        loading,
+        downloadCsv,
+        totalPages,
+        countFiltered,
+        count,
+        rows,
+        first,
+        last,
+        toggleSort
+    }
+}

package/app/assets/index.ts

@@ -0,0 +1,8 @@
+import { useConfigStore } from './stores'
+
+export default {
+    install: () => {
+        const config = useConfigStore()
+        config.load()
+    }
+}

package/app/assets/interfaces/alerts.ts

@@ -0,0 +1,16 @@
+/**
+ * Alert Interface
+ *
+ * Represents a common interface for alert components. This interface is used by
+ * API when an error occurs or a successful event occurs, and consumed by the
+ * interface.
+ */
+import { Severity } from './severity'
+
+export interface AlertInterface {
+    title?: string
+    description?: string
+    style?: Severity | keyof typeof Severity
+    closeBtn?: boolean
+    hideIcon?: boolean
+}

package/app/assets/interfaces/common.ts

@@ -0,0 +1,8 @@
+/**
+ * Common Interfaces
+ *
+ * Returns miscellaneous interfaces that are used throughout the application.
+ */
+export interface AssociativeArray {
+    [key: string]: string | null
+}

package/app/assets/interfaces/index.ts

@@ -0,0 +1,4 @@
+export type { AlertInterface } from './alerts'
+export type { AssociativeArray } from './common'
+export { Severity } from './severity'
+export type { Sprunjer } from './sprunjer'

package/app/assets/interfaces/severity.ts

@@ -0,0 +1,24 @@
+/**
+ * Severity Enum
+ *
+ * This is a shared enum used to define the severity of different components
+ * (e.g., alert, button, etc.). This makes it easier to reference severity
+ * levels across multiple components, also defining a common concept across
+ * themes.
+ *
+ * Template components must accept all values of this enum as valid input.
+ * However, themes may choose to ignore or bind some values to another style.
+ * For example, a theme might not have an 'Info' colored button. In this case,
+ * the theme's button component must accept 'Info' as a valid input, but it can
+ * map it to the 'Primary' style.
+ */
+export enum Severity {
+    Primary = 'Primary',
+    Secondary = 'Secondary',
+    Success = 'Success',
+    Warning = 'Warning',
+    Danger = 'Danger',
+    Info = 'Info',
+    Muted = 'Muted', // Aka, Disabled
+    Default = 'Default' // No-style or default style
+}

package/app/assets/interfaces/sprunjer.ts

@@ -0,0 +1,26 @@
+/**
+ * Sprunjer Interface
+ *
+ * Represents the interface for the Sprunjer composable.
+ */
+import type { Ref, ComputedRef } from 'vue'
+import type { AssociativeArray } from '.'
+
+export interface Sprunjer {
+    dataUrl: any
+    size: Ref<number>
+    page: Ref<number>
+    sorts: Ref<AssociativeArray>
+    filters: Ref<AssociativeArray>
+    data: Ref<any>
+    fetch: () => void
+    loading: Ref<boolean>
+    totalPages: ComputedRef<number>
+    downloadCsv: () => void
+    countFiltered: ComputedRef<number>
+    count: ComputedRef<number>
+    rows: ComputedRef<any[]>
+    first: ComputedRef<number>
+    last: ComputedRef<number>
+    toggleSort: (column: string) => void
+}

package/app/assets/stores/config.ts

@@ -0,0 +1,30 @@
+/**
+ * Config Store
+ *
+ * This store is used to access the configuration of the application from the
+ * API.
+ */
+import { defineStore } from 'pinia'
+import axios from 'axios'
+import { getProperty } from 'dot-prop'
+
+export const useConfigStore = defineStore('config', {
+    persist: true,
+    state: () => {
+        return {
+            config: {}
+        }
+    },
+    getters: {
+        get: (state) => {
+            return (key: string, value?: any): any => getProperty(state.config, key, value)
+        }
+    },
+    actions: {
+        async load() {
+            axios.get('/api/config').then((response) => {
+                this.config = response.data
+            })
+        }
+    }
+})

package/app/assets/stores/index.ts

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

package/app/assets/tests/interfaces/alerts.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from 'vitest'
+import { type AlertInterface, Severity } from '../../interfaces'
+
+describe('AlertInterface', () => {
+    test('should create an alert with title and description', () => {
+        const alert: AlertInterface = {
+            title: 'Test Alert',
+            description: 'This is a test alert'
+        }
+
+        expect(alert.title).toBe('Test Alert')
+        expect(alert.description).toBe('This is a test alert')
+    })
+
+    test('should create an alert with style', () => {
+        const alert: AlertInterface = {
+            style: Severity.Success
+        }
+
+        expect(alert.style).toBe(Severity.Success)
+    })
+
+    test('should create an alert with close button and hide icon', () => {
+        const alert: AlertInterface = {
+            closeBtn: true,
+            hideIcon: true
+        }
+
+        expect(alert.closeBtn).toBe(true)
+        expect(alert.hideIcon).toBe(true)
+    })
+})
+
+describe('Severity', () => {
+    test('should have the correct values', () => {
+        expect(Severity.Primary).toBe('Primary')
+        expect(Severity.Secondary).toBe('Secondary')
+        expect(Severity.Success).toBe('Success')
+        expect(Severity.Warning).toBe('Warning')
+        expect(Severity.Danger).toBe('Danger')
+        expect(Severity.Info).toBe('Info')
+    })
+})

package/app/assets/tests/plugin.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test, vi } from 'vitest'
+import { useConfigStore } from '../stores/config'
+import plugin from '..'
+import * as Config from '../stores/config'
+
+const mockConfigStore = {
+    load: vi.fn()
+}
+
+describe('Plugin', () => {
+    test('should install the plugin and initiate load', () => {
+        vi.spyOn(Config, 'useConfigStore').mockReturnValue(mockConfigStore as any)
+
+        plugin.install()
+
+        expect(useConfigStore).toHaveBeenCalled()
+        expect(mockConfigStore.load).toHaveBeenCalled()
+    })
+})

package/app/assets/tests/stores/config.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, beforeEach, test, vi } from 'vitest'
+import { setActivePinia, createPinia } from 'pinia'
+import axios from 'axios'
+import { useConfigStore } from '../../stores/config'
+
+const testConfig = {
+    name: 'Test Config',
+    description: 'Test description',
+    api: {
+        url: 'https://api.example.com',
+        version: '1.0'
+    }
+}
+
+describe('Config Store', () => {
+    beforeEach(() => {
+        setActivePinia(createPinia())
+    })
+
+    test('should load config data', async () => {
+        // Arrange
+        const configStore = useConfigStore()
+        const response = { data: testConfig }
+        vi.spyOn(axios, 'get').mockResolvedValue(response as any)
+
+        // Assert initial state
+        expect(configStore.config).toEqual({})
+
+        // Act
+        await configStore.load()
+
+        // Assert
+        expect(axios.get).toHaveBeenCalledWith('/api/config')
+        expect(configStore.config).toStrictEqual(testConfig)
+
+        // Assert get method
+        expect(configStore.get('name')).toBe('Test Config')
+        expect(configStore.get('api.url')).toBe('https://api.example.com')
+        expect(configStore.get('api.version', '0.0')).toBe('1.0')
+        expect(configStore.get('api.key', 'API_KEY')).toBe('API_KEY')
+    })
+})

package/package.json

@@ -0,0 +1,76 @@
+{
+    "name": "@userfrosting/sprinkle-core",
+    "version": "6.0.0-alpha.1",
+    "type": "module",
+    "description": "Core Sprinkle for UserFrosting",
+    "funding": "https://opencollective.com/userfrosting",
+    "license": "MIT",
+    "author": "Louis Charette (https://bbqsoftwares.com/)",
+    "contributors": [
+        "Alexander Weissman (https://alexanderweissman.com/)",
+        "Louis Charette (https://bbqsoftwares.com/)"
+    ],
+    "keywords": [
+        "UserFrosting",
+        "Core",
+        "Sprinkle"
+    ],
+    "homepage": "https://github.com/userfrosting/sprinkle-core#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/userfrosting/sprinkle-core.git"
+    },
+    "bugs": {
+        "url": "https://github.com/userfrosting/UserFrosting/issues"
+    },
+    "exports": {
+        ".": "./app/assets/index.ts",
+        "./interfaces": "./app/assets/interfaces/index.ts",
+        "./stores": "./app/assets/stores/index.ts",
+        "./composables": "./app/assets/composables/index.ts"
+    },
+    "files": [
+        "app/assets/"
+    ],
+    "dependencies": {
+        "dot-prop": "^9.0.0"
+    },
+    "peerDependencies": {
+        "axios": "^1.5.0",
+        "pinia": "^2.1.6",
+        "pinia-plugin-persistedstate": "^3.2.0",
+        "vue": "^3.4.21"
+    },
+    "devDependencies": {
+        "@rushstack/eslint-patch": "^1.8.0",
+        "@tsconfig/node20": "^20.1.4",
+        "@types/node": "^20.12.5",
+        "@vitejs/plugin-vue": "^5.0.4",
+        "@vitest/coverage-v8": "^1.6.0",
+        "@vue/eslint-config-prettier": "^9.0.0",
+        "@vue/eslint-config-typescript": "^13.0.0",
+        "@vue/test-utils": "^2.4.6",
+        "@vue/tsconfig": "^0.5.1",
+        "eslint": "^8.57.0",
+        "eslint-plugin-vue": "^9.23.0",
+        "happy-dom": "^15.11.6",
+        "less": "^4.2.0",
+        "npm-run-all2": "^6.1.2",
+        "prettier": "^3.2.5",
+        "vite": "^5.2.8",
+        "vite-plugin-dts": "^4.0.0",
+        "vitest": "^1.6.0",
+        "vue": "^3.4.21",
+        "vue-router": "^4.2.4",
+        "vue-tsc": "^2.0.11"
+    },
+    "scripts": {
+        "dev": "vite",
+        "typecheck": "vue-tsc --noEmit",
+        "build": "vue-tsc && vite build",
+        "lint": "eslint app/assets/ --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",
+        "format": "prettier --write app/assets/",
+        "test": "vitest",
+        "coverage": "vitest run --coverage"
+    }
+}