From f83020cd1fb62b90719921bbcc2add3fcf9f655d Mon Sep 17 00:00:00 2001
From: Sami Mazouz <sychocouldy@gmail.com>
Date: Sat, 12 Oct 2024 14:37:10 +0100
Subject: [PATCH] feat: add `Admin.generalIndexItems` extender (#4068)

* feat: add `Admin.generalIndexItems` extender
* docs
---
 .../package-manager/js/src/admin/extend.tsx   | 23 ++++++++++++++++-
 .../js/src/admin/states/GeneralSearchIndex.ts | 19 ++++++++++++++
 .../core/js/src/common/extenders/Admin.ts     | 25 ++++++++++++++++++-
 3 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/extensions/package-manager/js/src/admin/extend.tsx b/extensions/package-manager/js/src/admin/extend.tsx
index 711320b47..33f7bab60 100644
--- a/extensions/package-manager/js/src/admin/extend.tsx
+++ b/extensions/package-manager/js/src/admin/extend.tsx
@@ -27,5 +27,26 @@ export default [
       help: app.translator.trans('flarum-extension-manager.admin.settings.task_retention_days_help'),
       type: 'number',
     }))
-    .page(SettingsPage),
+    .page(SettingsPage)
+    .generalIndexItems('settings', () => [
+      {
+        id: 'minimum-stability',
+        label: app.translator.trans('flarum-extension-manager.admin.composer.minimum_stability.label', {}, true),
+        help: app.translator.trans('flarum-extension-manager.admin.composer.minimum_stability.help', {}, true),
+      },
+      {
+        id: 'repositories',
+        label: app.translator.trans('flarum-extension-manager.admin.composer.repositories.label', {}, true),
+        help: app.translator.trans('flarum-extension-manager.admin.composer.repositories.help', {}, true),
+      },
+      {
+        id: 'composer-auth',
+        label: app.translator.trans('flarum-extension-manager.admin.auth_config.title', {}, true),
+      },
+      {
+        id: 'updates',
+        label: app.translator.trans('flarum-extension-manager.admin.updater.updater_title', {}, true),
+        help: app.translator.trans('flarum-extension-manager.admin.updater.updater_help', {}, true),
+      },
+    ]),
 ];
diff --git a/framework/core/js/src/admin/states/GeneralSearchIndex.ts b/framework/core/js/src/admin/states/GeneralSearchIndex.ts
index 14d5a0d33..2b60847fe 100644
--- a/framework/core/js/src/admin/states/GeneralSearchIndex.ts
+++ b/framework/core/js/src/admin/states/GeneralSearchIndex.ts
@@ -1,9 +1,28 @@
 export type GeneralIndexItem = {
+  /**
+   * The unique identifier for this index item.
+   */
   id: string;
+  /**
+   * Optional: The tree path to this item, used for grouping in the search results.
+   */
   tree?: string[];
+  /**
+   * The label to display in the search results.
+   */
   label: string;
+  /**
+   * Optional: The description to display in the search results.
+   */
   help?: string;
+  /**
+   * Optional: The URL to navigate to when this item is selected.
+   * The default is to navigate to the extension page.
+   */
   link?: string;
+  /**
+   * Optional: A callback that returns a boolean indicating whether this item should be visible in the search results.
+   */
   visible?: () => boolean;
 };
 
diff --git a/framework/core/js/src/common/extenders/Admin.ts b/framework/core/js/src/common/extenders/Admin.ts
index e53b89837..ed29f30dd 100644
--- a/framework/core/js/src/common/extenders/Admin.ts
+++ b/framework/core/js/src/common/extenders/Admin.ts
@@ -2,12 +2,14 @@ import IExtender, { IExtensionModule } from './IExtender';
 import type AdminApplication from '../../admin/AdminApplication';
 import type { CustomExtensionPage, SettingConfigInternal } from '../../admin/utils/AdminRegistry';
 import type { PermissionConfig, PermissionType } from '../../admin/components/PermissionGrid';
-import Mithril from 'mithril';
+import type Mithril from 'mithril';
+import type { GeneralIndexItem } from '../../admin/states/GeneralSearchIndex';
 
 export default class Admin implements IExtender<AdminApplication> {
   protected settings: { setting?: () => SettingConfigInternal; customSetting?: () => Mithril.Children; priority: number }[] = [];
   protected permissions: { permission: () => PermissionConfig; type: PermissionType; priority: number }[] = [];
   protected customPage: CustomExtensionPage | null = null;
+  protected generalIndexes: { settings?: () => GeneralIndexItem[]; permissions?: () => GeneralIndexItem[] } = {};
 
   /**
    * Register a setting to be shown on the extension's settings page.
@@ -45,6 +47,15 @@ export default class Admin implements IExtender<AdminApplication> {
     return this;
   }
 
+  /**
+   * Register a custom general search index entry.
+   */
+  generalIndexItems(type: 'settings' | 'permissions', items: () => GeneralIndexItem[]) {
+    this.generalIndexes[type] = items;
+
+    return this;
+  }
+
   extend(app: AdminApplication, extension: IExtensionModule) {
     app.registry.for(extension.name);
 
@@ -59,5 +70,17 @@ export default class Admin implements IExtender<AdminApplication> {
     if (this.customPage) {
       app.registry.registerPage(this.customPage);
     }
+
+    app.generalIndex.for(extension.name);
+
+    Object.keys(this.generalIndexes).forEach((key) => {
+      if (key !== 'settings' && key !== 'permissions') return;
+
+      const callback = this.generalIndexes[key];
+
+      if (callback) {
+        app.generalIndex.add(key, callback());
+      }
+    });
   }
 }