Added basic concepts to the docs

docs/installation-and-setup.md

@@ -20,24 +20,120 @@ php artisan vendor:publish --provider="Javaabu\Stats\StatsServiceProvider" --tag
 This is the default content of the config file:
 
 ```php
-// TODO
-```
+<?php
 
-# Setting up the API Route
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Whether the week should start on Sunday
+    |--------------------------------------------------------------------------
+    |
+    | Used to determine the start day of week.
+    | true - Week starts on Sunday
+    | false - Week starts on Monday
+    |
+    */
 
-Add the following code to your `api.php` route file. You can place it as a publicly accessible JSON route. The package will automatically add the `stats.view-time-series` middleware which will ensure users will be allowed to view only stats they're authorized to view.
+    'week_starts_on_sunday' => true,
 
-This will add a `GET {api_base_url}/stats/time-series` endpoint.
 
-```php
-\Javaabu\Stats\TimeSeriesStats::registerApiRoute();
-```
+    /*
+    |--------------------------------------------------------------------------
+    | The locale used for dates
+    |--------------------------------------------------------------------------
+    |
+    | The locale used to format dates
+    |
+    */
 
-# Setting up the Admin Routes
+    'date_locale' => 'en_GB',
 
-Add the following code to your `admin.php` (if using Javaabu's Laravel Skeleton) or to your `web.php` route file.
-This will add a `GET {admin_base_url}/stats/time-series` and a `POST {admin_base_url}/stats/time-series` endpoint.
+    /*
+    |--------------------------------------------------------------------------
+    | Date formats for different time modes
+    |--------------------------------------------------------------------------
+    |
+    | Used to format the date when generating stats in different time series modes
+    | Uses momentJS compatible formats
+    |
+    */
+
+    'date_formats' => [
+        'hour' => 'D MMM YY hh:mm A',
+        'day' => 'D MMM YY',
+        'week' => 'gggg - \W\e\e\k w',
+        'month' => 'YYYY MMMM',
+        'year' => 'YYYY',
+    ],
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default time series mode
+    |--------------------------------------------------------------------------
+    |
+    | Default mode to show on the stats form
+    |
+    */
+
+    'default_time_series_mode' => \Javaabu\Stats\Enums\TimeSeriesModes::DAY,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default date range
+    |--------------------------------------------------------------------------
+    |
+    | Default date range to show on stats
+    |
+    */
+
+    'default_date_range' => \Javaabu\Stats\Enums\PresetDateRanges::LAST_7_DAYS,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default CSS Framework
+    |--------------------------------------------------------------------------
+    |
+    | This option controls the default CSS framework that will be used by the
+    | package when rendering views
+    |
+    | Supported: "material-admin-26"
+    |
+    */
+
+    'framework' => 'material-admin-26',
+
+    /*
+    |--------------------------------------------------------------------------
+    | Default Layout
+    |--------------------------------------------------------------------------
+    |
+    | Default layout view for stats views
+    |
+    */
+
+    'default_layout' => 'layouts.admin',
+
+    /*
+    |--------------------------------------------------------------------------
+    | Scripts Stack
+    |--------------------------------------------------------------------------
+    |
+    | The name of the stack to push scripts
+    |
+    */
+
+    'scripts_stack' => 'scripts',
+
+   /*
+   |--------------------------------------------------------------------------
+   | View for time series stats
+   |--------------------------------------------------------------------------
+   |
+   | Used in the main time series stats controller
+   |
+   */
+
+    'time_series_stats_view' => 'stats::material-admin-26.time-series-stats.index',
+];
 
-```php
-\Javaabu\Stats\TimeSeriesStats::registerRoutes();
 ```

docs/intro.md

@@ -11,4 +11,4 @@ This package is currently under development. If anything works, that's a surpris
 
 :::
 
-[Stats](https://github.com/Javaabu/stats) Simplifies stats generation for Laravel.
+[Stats](https://github.com/Javaabu/stats) Simplifies stats generation for Laravel. This package allows you to easily define time series statistics and visualize them through an interactive graph.

docs/time-series/_category_.json

@@ -0,0 +1,11 @@
+{
+    "position": 1.3,
+    "label": "Time Series Stats",
+    "collapsible": true,
+    "collapsed": false,
+    "link": {
+        "type": "generated-index",
+        "slug": "/stats/_categories/time-series",
+        "description": "How to define and use time series statistics"
+    }
+}

docs/time-series/basic-concepts.md

@@ -0,0 +1,93 @@
+---
+title: Basic Concepts
+sidebar_position: 2
+---
+
+Time series statistics are any statistic that varies over time. Using time series stats, you can track any numerical value that changes over time within a given time period. For example, this could be daily user signups, weekly sales, etc. Currently, this package allows viewing time series stats in the following modes:
+
+- Hour
+- Day
+- Week 
+- Month
+- Year
+
+# Instantiating a stat class
+
+To use a Time Series Stat Repository, you need to make a new instance of the class by providing a date range to generate the stats for.
+The data range should be either a `\Javaabu\Stats\Enums\PresetDateRanges` enum or an `\Javaabu\Stats\Support\ExactDateRange` object.
+
+For preset date ranges, the package offers the following presets:
+- `TODAY`
+- `YESTERDAY`
+- `THIS_WEEK`
+- `LAST_WEEK`
+- `THIS_MONTH`
+- `LAST_MONTH`
+- `THIS_YEAR`
+- `LAST_YEAR`
+- `LAST_7_DAYS`
+- `LAST_14_DAYS`
+- `LAST_30_DAYS`
+- `LIFETIME`
+
+For exact date ranges, you can provide your own start and end date:
+
+```php
+use \Javaabu\Stats\Support\ExactDateRange;
+
+$date_range = new ExactDateRange('2024-07-30 12:32:00', '2024-08-02 13:42:00');
+```
+
+Once you've a date range, you can instantiate a new instance of the stat:
+
+```php
+use \Javaabu\Stats\Repositories\TimeSeries\UserLoginsRepository;
+use \Javaabu\Stats\Enums\PresetDateRanges;
+
+$stat = new UserLoginsRepository(PresetDateRanges::LAST_7_DAYS);
+```
+
+You can also instantiate a stat using the `TimeSeriesStats::createFromMetric()` method. When calling this method, you have to use the registered metric name for the stat.
+
+```php
+use \Javaabu\Stats\TimeSeriesStats;
+use \Javaabu\Stats\Enums\PresetDateRanges;
+
+$stat = TimeSeriesStats::createFromMetric('user_logins', PresetDateRanges::LAST_7_DAYS);
+```
+
+# Getting the results from a stat class
+
+Once you have instantiated a stat class, you can use the stat class to get the results in any of the available Time Series modes:
+
+```php
+use \Javaabu\Stats\Enums\TimeSeriesModes;
+
+$results = $stat->results(TimeSeriesModes::DAY); // returns a collection
+```
+
+Note that when calling the `results` method, the returned collection will not have any data for missing days (or hours, weeks, etc. depending on the mode you're using) within the given date range.
+
+# Formatting the results
+
+To have the missing days also included as `0` values, you can format your results:
+
+```php
+$formatted_results = $stat->format(
+    'default', // which format to use
+    TimeSeriesModes::DAY); // returns an array
+```
+
+# Filtering the results
+
+Some stats will also allow you to filter the results using certain allowed filter values. For example, the `UserLoginsRepository` allows filtering by a specific user. To filter the results, you can provide an array of filters when you instantiate the stat.
+
+```php
+use \Javaabu\Stats\TimeSeriesStats;
+use \Javaabu\Stats\Enums\PresetDateRanges;
+
+$stat = TimeSeriesStats::createFromMetric('user_logins', PresetDateRanges::LAST_7_DAYS, ['user' => 2]);
+$filtered_results = $stat->results(TimeSeriesModes::DAY);
+```
+
+

docs/time-series/defining-time-series-stats.md

@@ -0,0 +1,24 @@
+---
+title: Defining time series stats
+sidebar_position: 3
+---
+
+Time series statistics are any statistic that varies over time. Using time series stats, you can track any numerical value that changes over time within a given time period. For example, this could be daily user signups, weekly sales, etc. Currently, this package allows viewing time series stats in the following modes:
+
+- Hour
+- Day
+- Week 
+- Month
+- Year
+
+So to define a time series stat, you have to provide the query for each of these modes, and a query to get the total for the full date range.
+Luckily, this package makes the process easy for you by providing a set of abstract Stat Repository classes that you can extend to define your stat.
+
+# Aggregate Stats
+
+
+
+# Count Stats
+
+
+

docs/time-series/getting-started.md

@@ -0,0 +1,99 @@
+---
+title: Getting started
+sidebar_position: 2
+---
+
+# JavaScript Prerequisites
+
+Before getting started, you need to ensure the following JS libraries has been installed and copied to the `public/vendors` directory:
+
+- [`chart.js`](https://www.chartjs.org/)
+- [`jquery-sparkline`](https://omnipotent.net/jquery.sparkline)
+- [`flot`](https://www.flotcharts.org/)
+- [`flot.curvedlines`](http://curvedlines.michaelzinsmaier.de/)
+- [`flot-orderbars`](https://www.npmjs.com/package/flot-orderbars)
+
+If you don't have these libraries already installed, you can install the packages by running the following command:
+
+```bash
+npm install chart.js jquery-sparkline flot flot.curvedlines flot-orderbars --save
+```
+
+If using Javaabu's Laravel Skeleton, these packages should already be installed for you. You should check the `material-admin.config.js` file for any missing libraries and add them there. After adding any missing libraries, you can run `npm run material-admin`.
+
+# Setting up permissions
+
+By default, stats can only be viewed by users that have a `view_stats` permission. If you are using [`spatie/laravel-permission`](https://github.com/spatie/laravel-permission), you can seed a permission for `view_stats` and grant the permission to the users you want to be able to view the stats.
+
+It is possible to define specific permissions for each stat you create, which we will cover how to do later.
+
+# Setting up the API Route
+
+For generating the time series stats graph, the data is loaded from an API. For this, you need to register the API routes for the package.
+
+Add the following code to your `api.php` route file. You can place it as a publicly accessible JSON route. The package will automatically add the `stats.view-time-series` middleware which will ensure users will be allowed to view only stats they're authorized to view.
+
+This will add a `GET {api_base_url}/stats/time-series` endpoint.
+
+```php
+// inside api.php route file
+
+/**
+ * Public routes
+ */
+Route::group([
+    'middleware' => ['oauth.client:read'],
+], function () {   
+    /**
+     * Public JSON routes
+     */
+    Route::group([
+        'middleware' => ['json'],
+    ], function () {       
+
+        \Javaabu\Stats\TimeSeriesStats::registerApiRoute();
+
+    });
+});
+```
+
+# Setting up the Admin Routes
+
+For viewing all the stats in one place, the package comes with a page for displaying the interactive stats graph and exporting the generated stats. To setup this page, you need to register the admin routes for the page.
+
+Add the following code to your `admin.php` (if using Javaabu's Laravel Skeleton) or to your `web.php` route file.
+This will add a `GET {admin_base_url}/stats/time-series` and a `POST {admin_base_url}/stats/time-series` endpoint.
+
+```php
+// inside admin
+
+/**
+ * Protected routes
+ */
+Route::group([
+    'middleware' => ['auth:web_admin', 'active:web_admin', 'password-update-not-required:web_admin'],
+], function () {
+
+    /**
+     * Stats
+     */
+    \Javaabu\Stats\TimeSeriesStats::registerRoutes();
+});
+
+```
+
+# Setting up sidebar
+
+If you're using Javaabu's Laravel Skeleton, you should also add a link to the stats page to your admin sidebar.
+
+```php
+// inside AdminSidebar.php
+...
+MenuItem::make(__('Stats'))
+    ->controller(\Javaabu\Stats\Http\Controllers\TimeSeriesStatsController::class)
+    ->can('view_stats')
+    ->icon('zmdi-trending-up'),
+...
+```
+
+