refactor(color): unify color sanitizing and picking behind shared components

- Add AKSRT\Core\Color::sanitize($value, $allow_alpha) as the single PHP
  color sanitizer; replace sanitize_hex_color calls and per-class regexes
  (FloatButtons, FieldSchema, ThemeSearch, icon cards, TicketStatusService)
- SchemaProvider / ControllerBase sanitize `color` fields as colors;
  alpha kept only when the schema sets showAlpha
- Split SchemaProvider OAuth validation and option matching into sibling
  traits to stay under the 1000-line limit
- Add AksColorPicker.vue + utils/color.js mirroring the PHP rules; AksField,
  FloatBtnCommonFields and TicketStatusPanel use it
- Widget background color input now uses wpColorPicker
- Remove dead AksCompositeField dimensions/spacing/background branches and
  the unused Gutenberg ColorPicker var
- Add color-unification contract test; update harness requires and tests

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tests/widget-system/captcha-security-harness.php

@@ -88,6 +88,9 @@ namespace {
 	require dirname(__DIR__, 2) . '/inc/modules/captcha.php';
 	require dirname(__DIR__, 2) . '/src/Attachment/UploadLimits.php';
 	require dirname(__DIR__, 2) . '/src/Admin/Schema/SchemaPermissions.php';
+	require dirname(__DIR__, 2) . '/src/Core/Color.php';
+	require dirname(__DIR__, 2) . '/src/Admin/SchemaProviderOAuthValidation.php';
+	require dirname(__DIR__, 2) . '/src/Admin/SchemaProviderOptionMatch.php';
 	require dirname(__DIR__, 2) . '/src/Admin/SchemaProvider.php';
 
 	function check(bool $condition, string $message): void {

tests/widget-system/color-unification-contract.test.cjs

@@ -0,0 +1,77 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const root = path.resolve(__dirname, '../..');
+const read = (file) => fs.readFileSync(path.join(root, file), 'utf8');
+
+function walk(dir, exts, out = []) {
+  for (const entry of fs.readdirSync(path.join(root, dir), { withFileTypes: true })) {
+    const rel = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (['node_modules', 'build', 'vendor'].includes(entry.name)) continue;
+      walk(rel, exts, out);
+    } else if (exts.some((ext) => entry.name.endsWith(ext))) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+test('n-color-picker is used only inside the shared AksColorPicker', () => {
+  const offenders = walk('assets/admin/src', ['.vue', '.js'])
+    .filter((file) => /n-color-picker|NColorPicker/.test(read(file)))
+    .map((file) => file.replace(/\\/g, '/'));
+  assert.deepEqual(offenders, ['assets/admin/src/components/form/AksColorPicker.vue']);
+});
+
+test('PHP color sanitizing goes through AKSRT\\Core\\Color only', () => {
+  const offenders = [...walk('src', ['.php']), ...walk('inc', ['.php'])]
+    .filter((file) => /sanitize_hex_color\(|rgba\?\\\(/.test(read(file)))
+    .map((file) => file.replace(/\\/g, '/'))
+    .filter((file) => file !== 'src/Core/Color.php');
+  assert.deepEqual(offenders, []);
+});
+
+test('schema color fields sanitize via Color with showAlpha opt-in', () => {
+  const provider = read('src/Admin/SchemaProvider.php');
+  assert.match(provider, /'color'\s*=>\s*'color'/);
+  assert.match(provider, /case 'color_alpha':\s*return \\AKSRT\\Core\\Color::sanitize\(\$value, true\)/);
+  assert.match(provider, /showAlpha/);
+  const field = read('assets/admin/src/components/form/AksField.vue');
+  assert.match(field, /<AksColorPicker[\s\S]*?:alpha="!!schema\.showAlpha"/);
+});
+
+test('dead composite branches are gone', () => {
+  const composite = read('assets/admin/src/components/form/AksCompositeField.vue');
+  assert.doesNotMatch(composite, /'dimensions'|'spacing'|'background'|AksMediaField/);
+  assert.doesNotMatch(read('assets/js/gutenberg-blocks.js'), /ColorPicker/);
+});
+
+test('JS normalizeColor mirrors PHP Color::sanitize', async () => {
+  const { normalizeColor } = await import(
+    'file://' + path.join(root, 'assets/admin/src/utils/color.js').replace(/\\/g, '/')
+  );
+  const cases = [
+    ['#ABC', false], ['abcdef', false], ['#abcd', false], ['#11223344', false], ['rgb(1,2,3)', false],
+    ['#abcd', true], ['#11223344', true], ['rgb(1,2,3)', true], ['RGBA( 10 , 20 , 30 , .5 )', true],
+    ['rgba(1,2,3,0.12345)', true], ['rgba(1,2,3,1.0)', true], ['rgb(256,0,0)', true],
+    ['red', true], ['', true], ['  #FFF  ', false],
+  ];
+  const php = `require 'src/Core/Color.php';`
+    + `foreach (json_decode($argv[1], true) as [$v, $a]) { echo AKSRT\\Core\\Color::sanitize($v, $a), "\\n"; }`;
+  const out = execFileSync('php', ['-d', 'display_errors=1', '-r', `define('ABSPATH', '/');${php}`, JSON.stringify(cases)], {
+    cwd: root,
+    encoding: 'utf8',
+  }).split('\n').slice(0, cases.length);
+  assert.deepEqual(cases.map(([v, a]) => normalizeColor(v, a)), out);
+});
+
+test('widget background color input is wpColorPicker-enhanced like top-level color fields', () => {
+  const renderer = read('src/WidgetSystem/FormRenderer.php');
+  assert.match(renderer, /\$key \. '\[color\]'[^\n]+'widefat aksrt-widget-color'\)/);
+  assert.match(renderer, /class="' \. esc_attr\(\$class\) \. '"/);
+  assert.match(read('assets/widgets/admin.js'), /\.aksrt-widget-color'\)\.wpColorPicker\(\)/);
+});

tests/widget-system/oauth-security-harness.php

@@ -90,6 +90,9 @@ namespace {
 	require dirname(__DIR__, 2) . '/src/Auth/OAuth.php';
 	require dirname(__DIR__, 2) . '/src/Admin/Schema/SchemaUsers.php';
 	require dirname(__DIR__, 2) . '/src/Admin/Schema/Users/SchemaUsersTicket.php';
+	require dirname(__DIR__, 2) . '/src/Core/Color.php';
+	require dirname(__DIR__, 2) . '/src/Admin/SchemaProviderOAuthValidation.php';
+	require dirname(__DIR__, 2) . '/src/Admin/SchemaProviderOptionMatch.php';
 	require dirname(__DIR__, 2) . '/src/Admin/SchemaProvider.php';
 
 	function check(bool $condition, string $message): void {

tests/widget-system/page-display-save-harness.php

@@ -147,6 +147,9 @@ namespace {
 	require_once dirname(__DIR__, 2) . '/src/Ledger/AssetAmount.php';
 	require_once dirname(__DIR__, 2) . '/src/Admin/Schema/SchemaPageDisplay.php';
 	require_once dirname(__DIR__, 2) . '/src/Admin/Schema/SchemaPayment.php';
+	require_once dirname(__DIR__, 2) . '/src/Core/Color.php';
+	require_once dirname(__DIR__, 2) . '/src/Admin/SchemaProviderOAuthValidation.php';
+	require_once dirname(__DIR__, 2) . '/src/Admin/SchemaProviderOptionMatch.php';
 	require_once dirname(__DIR__, 2) . '/src/Admin/SchemaProvider.php';
 	require_once dirname(__DIR__, 2) . '/src/Admin/ControllerBase.php';
 	require_once dirname(__DIR__, 2) . '/inc/helpers/homepage/header-components.php';

tests/widget-system/ticket-schema-version.test.cjs

@@ -120,5 +120,6 @@ test('TicketStatusService seeds mirror the migrator and guard the default row',
   assert.match(service, /if \(self::is_closed\(\$from\)\) \{\s*\n\s*return false;/);
   // 颜色只接受 #rgb / #rrggbb。
   assert.match(service, /'#6b7280'/);
-  assert.match(service, /preg_match\('\/\^#\(\?:\[0-9a-f\]\{3\}\|\[0-9a-f\]\{6\}\)\$\/'/);
+  assert.match(service, /\\AKSRT\\Core\\Color::sanitize\(\$color\)/);
+  assert.doesNotMatch(service, /preg_match\('\/\^#/);
 });

tests/widget-system/ticket-spa-config-contract.test.cjs

@@ -80,8 +80,12 @@ test('panels enforce the backend guards instead of trusting the client', () => {
   // 默认状态的编辑/删除入口在前端禁用，但后端 TicketConfigRest 仍有 409 兜底。
   assert.match(status, /disabled: row\.is_default/);
   // 颜色必须落在 TicketStatusService::sanitize_color() 接受的范围内。
-  assert.match(status, /\^#\(\?:\[0-9a-f\]\{3\}\|\[0-9a-f\]\{6\}\)\$/i);
+  assert.match(status, /import \{ toHex \} from '@\/utils\/color\.js'/);
+  assert.match(status, /<AksColorPicker/);
+  assert.doesNotMatch(status, /n-color-picker|HEX_RE/);
   assert.match(status, /#6b7280/);
+  const color = read('assets/admin/src/utils/color.js');
+  assert.match(color, /export const HEX_RE = \/\^#\?\(\[0-9a-f\]\{3\}\|\[0-9a-f\]\{6\}\)\$\/i/);
 
   const prereply = read('assets/admin/src/pages/users/partials/ticket/TicketPrereplyPanel.vue');
   // 排序接口要求全量 ID。

tests/widget-system/vip-settings-structured-harness.php

@@ -62,6 +62,9 @@ namespace {
 	require dirname(__DIR__, 2) . '/src/Ledger/AssetAmount.php';
 	require dirname(__DIR__, 2) . '/src/Settings/PaymentRuntime.php';
 	require dirname(__DIR__, 2) . '/src/Admin/Schema/SchemaPayment.php';
+	require dirname(__DIR__, 2) . '/src/Core/Color.php';
+	require dirname(__DIR__, 2) . '/src/Admin/SchemaProviderOAuthValidation.php';
+	require dirname(__DIR__, 2) . '/src/Admin/SchemaProviderOptionMatch.php';
 	require dirname(__DIR__, 2) . '/src/Admin/SchemaProvider.php';
 	require dirname(__DIR__, 2) . '/src/Content/VipServicePackages.php';