From 9ff31d4de1f1719b034df5fa249f7d839f333fa3 Mon Sep 17 00:00:00 2001
From: Jonathan Miller <jmiller-moko@noreply.git.mokoconsulting.tech>
Date: Sun, 21 Jun 2026 17:27:09 -0500
Subject: [PATCH] =?UTF-8?q?feat:=20initial=20scaffold=20=E2=80=94=20packag?=
 =?UTF-8?q?e=20manifest=20with=20dlid/updateservers=20+=20first=20helper?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/Helper/DashboardHelper.php            | 120 ++++++++++++++++++
 source/pkg_mokosuitesight.xml                 |  26 ++++
 2 files changed, 146 insertions(+)
 create mode 100644 source/packages/plg_system_mokosuitesight/src/Helper/DashboardHelper.php
 create mode 100644 source/pkg_mokosuitesight.xml

diff --git a/source/packages/plg_system_mokosuitesight/src/Helper/DashboardHelper.php b/source/packages/plg_system_mokosuitesight/src/Helper/DashboardHelper.php
new file mode 100644
index 0000000..b68b103
--- /dev/null
+++ b/source/packages/plg_system_mokosuitesight/src/Helper/DashboardHelper.php
@@ -0,0 +1,120 @@
+<?php
+namespace Moko\Plugin\System\MokoSuiteSight\Helper;
+
+defined('_JEXEC') or die;
+
+use Joomla\CMS\Factory;
+use Joomla\Database\DatabaseInterface;
+
+/**
+ * Dashboard management — CRUD, widget layout, user assignments, sharing.
+ */
+class DashboardHelper
+{
+	/**
+	 * Get dashboards for the current user.
+	 */
+	public static function getForUser(?int $userId = null): array
+	{
+		$userId = $userId ?: (int) Factory::getApplication()->getIdentity()->id;
+		$db = Factory::getContainer()->get(DatabaseInterface::class);
+
+		$db->setQuery($db->getQuery(true)
+			->select('d.id, d.title, d.description, d.is_default, d.shared, d.created_at')
+			->select('(SELECT COUNT(*) FROM #__mokosuitesight_widgets w WHERE w.dashboard_id = d.id) AS widget_count')
+			->from($db->quoteName('#__mokosuitesight_dashboards', 'd'))
+			->where('(d.user_id = ' . (int) $userId . ' OR d.shared = 1)')
+			->order('d.is_default DESC, d.title ASC'));
+
+		return $db->loadObjectList() ?: [];
+	}
+
+	/**
+	 * Get a dashboard with all its widgets.
+	 */
+	public static function getWithWidgets(int $dashboardId): ?object
+	{
+		$db = Factory::getContainer()->get(DatabaseInterface::class);
+
+		$db->setQuery($db->getQuery(true)
+			->select('d.*')
+			->from($db->quoteName('#__mokosuitesight_dashboards', 'd'))
+			->where('d.id = ' . (int) $dashboardId));
+		$dashboard = $db->loadObject();
+
+		if (!$dashboard) {
+			return null;
+		}
+
+		$db->setQuery($db->getQuery(true)
+			->select('w.*')
+			->from($db->quoteName('#__mokosuitesight_widgets', 'w'))
+			->where('w.dashboard_id = ' . (int) $dashboardId)
+			->order('w.position ASC'));
+		$dashboard->widgets = $db->loadObjectList() ?: [];
+
+		foreach ($dashboard->widgets as &$w) {
+			$w->config = json_decode($w->config ?? '{}');
+		}
+
+		return $dashboard;
+	}
+
+	/**
+	 * Create a new dashboard.
+	 */
+	public static function create(string $title, ?string $description = null): object
+	{
+		$db = Factory::getContainer()->get(DatabaseInterface::class);
+		$filter = \Joomla\Filter\InputFilter::getInstance();
+
+		$dashboard = (object) [
+			'title'       => $filter->clean($title, 'STRING'),
+			'description' => $description ? $filter->clean($description, 'STRING') : null,
+			'user_id'     => (int) Factory::getApplication()->getIdentity()->id,
+			'layout'      => '{}',
+			'shared'      => 0,
+			'is_default'  => 0,
+			'created_at'  => Factory::getDate()->toSql(),
+		];
+
+		$db->insertObject('#__mokosuitesight_dashboards', $dashboard, 'id');
+
+		return (object) ['success' => true, 'dashboard_id' => (int) $dashboard->id];
+	}
+
+	/**
+	 * Add a widget to a dashboard.
+	 */
+	public static function addWidget(int $dashboardId, string $type, string $dataSource, array $config = []): object
+	{
+		$allowedTypes = ['counter', 'line_chart', 'bar_chart', 'pie_chart', 'gauge', 'table', 'sparkline', 'heatmap', 'funnel'];
+		if (!in_array($type, $allowedTypes, true)) {
+			throw new \InvalidArgumentException('Invalid widget type.');
+		}
+
+		$db = Factory::getContainer()->get(DatabaseInterface::class);
+
+		// Get next position
+		$db->setQuery($db->getQuery(true)
+			->select('COALESCE(MAX(position), 0) + 1')
+			->from('#__mokosuitesight_widgets')
+			->where('dashboard_id = ' . (int) $dashboardId));
+		$position = (int) $db->loadResult();
+
+		$widget = (object) [
+			'dashboard_id' => $dashboardId,
+			'type'         => $type,
+			'data_source'  => $dataSource,
+			'config'       => json_encode($config),
+			'position'     => $position,
+			'width'        => $config['width'] ?? 6,
+			'height'       => $config['height'] ?? 4,
+			'created_at'   => Factory::getDate()->toSql(),
+		];
+
+		$db->insertObject('#__mokosuitesight_widgets', $widget, 'id');
+
+		return (object) ['success' => true, 'widget_id' => (int) $widget->id];
+	}
+}
diff --git a/source/pkg_mokosuitesight.xml b/source/pkg_mokosuitesight.xml
new file mode 100644
index 0000000..396caba
--- /dev/null
+++ b/source/pkg_mokosuitesight.xml
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="utf-8"?>
+<extension type="package" method="upgrade">
+	<name>Package - MokoSuite Insight</name>
+	<packagename>mokosuitesight</packagename>
+	<version>01.00.00</version>
+	<creationDate>2026-06-21</creationDate>
+	<author>Moko Consulting</author>
+	<authorEmail>hello@mokoconsulting.tech</authorEmail>
+	<authorUrl>https://mokoconsulting.tech</authorUrl>
+	<copyright>Copyright (C) 2026 Moko Consulting. All rights reserved.</copyright>
+	<license>GNU General Public License version 3 or later; see LICENSE</license>
+	<description>MokoSuite Insight - real-time dashboards, data visualization, KPI monitoring, alerting. Connects to all MokoSuite modules.</description>
+	<php_minimum>8.3</php_minimum>
+	<dlid prefix="dlid=" suffix=""/>
+	<blockChildUninstall>true</blockChildUninstall>
+	<scriptfile>script.php</scriptfile>
+
+	<files folder="packages">
+		<file type="plugin" id="plg_system_mokosuitesight" group="system">plg_system_mokosuitesight.zip</file>
+		<file type="component" id="com_mokosuitesight">com_mokosuitesight.zip</file>
+	</files>
+
+	<updateservers>
+		<server type="extension" priority="1" name="Package - MokoSuite Insight">https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteInsight/updates.xml</server>
+	</updateservers>
+</extension>