phase 6 added helpdesk

Modules/Helpdesk/Support/Color.php

@@ -0,0 +1,158 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\Helpdesk\Support;
+
+use Closure;
+
+final class Color
+{
+    /**
+     * Standard approved Helpdesk badge colours.
+     *
+     * @var array<string, string>
+     */
+    public const PALETTE = [
+        'green' => '#16a34a',
+        'red' => '#dc2626',
+        'amber' => '#d97706',
+        'blue' => '#2563eb',
+        'indigo' => '#4f46e5',
+        'purple' => '#7c3aed',
+        'gray' => '#6b7280',
+    ];
+
+    /**
+     * Legacy Flux/Tailwind colour aliases normalised into the WMS palette.
+     *
+     * @var array<string, string>
+     */
+    private const ALIASES = [
+        'emerald' => 'green',
+        'lime' => 'green',
+        'rose' => 'red',
+        'yellow' => 'amber',
+        'orange' => 'amber',
+        'sky' => 'blue',
+        'cyan' => 'blue',
+        'violet' => 'purple',
+        'slate' => 'gray',
+        'zinc' => 'gray',
+        '' => 'gray',
+    ];
+
+    /**
+     * Resolve a stored palette key or supported custom hex value into a CSS colour.
+     */
+    public static function css(?string $color): string
+    {
+        $resolved = self::normalise($color);
+
+        if (self::isHex($resolved)) {
+            return $resolved;
+        }
+
+        return self::PALETTE[$resolved] ?? self::PALETTE['gray'];
+    }
+
+    /**
+     * Return a readable foreground colour for a badge background.
+     */
+    public static function text(?string $color): string
+    {
+        $hex = ltrim(self::css($color), '#');
+        $red = hexdec(substr($hex, 0, 2));
+        $green = hexdec(substr($hex, 2, 2));
+        $blue = hexdec(substr($hex, 4, 2));
+        $luminance = (($red * 299) + ($green * 587) + ($blue * 114)) / 1000;
+
+        return $luminance >= 150 ? '#111827' : '#ffffff';
+    }
+
+    /**
+     * Return approved palette options for settings dropdowns.
+     *
+     * @return array<string, array{name: string, hex: string, foreground: string}>
+     */
+    public static function options(): array
+    {
+        return collect(self::PALETTE)
+            ->mapWithKeys(fn (string $hex, string $name): array => [
+                $name => [
+                    'name' => str($name)->headline()->toString(),
+                    'hex' => $hex,
+                    'foreground' => self::text($hex),
+                ],
+            ])
+            ->all();
+    }
+
+    /**
+     * Return approved palette keys for validation rules.
+     *
+     * @return list<string>
+     */
+    public static function keys(): array
+    {
+        return array_keys(self::PALETTE);
+    }
+
+    /**
+     * Normalise legacy aliases and supported custom hex colours.
+     */
+    public static function normalise(?string $color): string
+    {
+        $value = strtolower(trim((string) $color));
+
+        if (self::isHex($value)) {
+            return $value;
+        }
+
+        return self::ALIASES[$value] ?? $value;
+    }
+
+    /**
+     * Determine whether the value is a supported six-character hex colour.
+     */
+    public static function isHex(?string $color): bool
+    {
+        return preg_match('/^#[a-f0-9]{6}$/', strtolower(trim((string) $color))) === 1;
+    }
+
+    /**
+     * Determine whether a stored colour is an approved palette key or custom hex colour.
+     */
+    public static function isAllowed(?string $color): bool
+    {
+        $resolved = self::normalise($color);
+
+        return self::isHex($resolved) || in_array($resolved, self::keys(), true);
+    }
+
+    /**
+     * Laravel validation rule allowing approved palette keys and six-character hex values.
+     */
+    public static function validationRule(): Closure
+    {
+        return static function (string $attribute, mixed $value, Closure $fail): void {
+            if (! self::isAllowed(is_string($value) ? $value : null)) {
+                $fail('The '.$attribute.' must be an approved Helpdesk colour or a valid hex colour such as #ffffff.');
+            }
+        };
+    }
+
+    /**
+     * Human-readable label for palette and custom hex values.
+     */
+    public static function label(?string $color): string
+    {
+        $resolved = self::normalise($color);
+
+        if (self::isHex($resolved)) {
+            return strtoupper($resolved);
+        }
+
+        return str($resolved ?: 'gray')->headline()->toString();
+    }
+}

Modules/Helpdesk/Support/ModuleInfo.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Modules\Helpdesk\Support;
+
+final class ModuleInfo
+{
+    /**
+     * Return the module name.
+     */
+    public static function name(): string
+    {
+        return 'Helpdesk';
+    }
+
+    /**
+     * Return the lowercase module name.
+     */
+    public static function nameLower(): string
+    {
+        return 'helpdesk';
+    }
+}