Merge pull request #10 from ConductionNL/wip/build-quick-search-2026-07-23

feat(tile-quick-search): on-dashboard quick-search launcher + archive

Author: rubenvdlinde

lib/Controller/AdminController.php

@@ -380,6 +380,15 @@ public function getSettings(): JSONResponse
      *                                                 unlimited).
      *                                                 dashboard-quota-limits
      *                                                 REQ-QUOTA-001.
+     * @param string|null $quicksearchFallbackTarget   On-dashboard quick-search
+     *                                                 no-match fallback:
+     *                                                 `'none'`,
+     *                                                 `'unified-search'`, or
+     *                                                 an `https` URL
+     *                                                 template containing
+     *                                                 `{query}`.
+     *                                                 tile-quick-search
+     *                                                 REQ-QSEARCH-004.
      *
      * @return JSONResponse The update confirmation.
      *
@@ -397,7 +406,8 @@ public function updateSettings(
         ?array $forcedShareGroups=null,
         ?bool $legacyWidgetBridgeEnabled=null,
         ?int $maxDashboardsPerUser=null,
-        ?int $maxWidgetsPerDashboard=null
+        ?int $maxWidgetsPerDashboard=null,
+        ?string $quicksearchFallbackTarget=null
     ): JSONResponse {
         try {
             $this->settingsService->updateSettings(
@@ -411,7 +421,8 @@ public function updateSettings(
                 forcedShareGroups: $forcedShareGroups,
                 legacyWidgetBridgeEnabled: $legacyWidgetBridgeEnabled,
                 maxDashboardsPerUser: $maxDashboardsPerUser,
-                maxWidgetsPerDashboard: $maxWidgetsPerDashboard
+                maxWidgetsPerDashboard: $maxWidgetsPerDashboard,
+                quicksearchFallbackTarget: $quicksearchFallbackTarget
             );
 
             return ResponseHelper::success(data: ['status' => 'ok']);

lib/Controller/PageController.php

@@ -27,6 +27,7 @@
 
 use OCA\LaunchPad\AppInfo\Application;
 use OCA\LaunchPad\Db\Dashboard;
+use OCA\LaunchPad\Service\AdminSettingsService;
 use OCA\LaunchPad\Service\AdminTemplateService;
 use OCA\LaunchPad\Service\DashboardService;
 use OCA\LaunchPad\Service\DashboardTreeService;
@@ -85,6 +86,13 @@ class PageController extends Controller
      *                                                           path doesn't
      *                                                           resolve to a
      *                                                           visible dashboard.
+     * @param AdminSettingsService         $adminSettingsService Source of the
+     *                                                           quick-search
+     *                                                           no-match
+     *                                                           fallback-target
+     *                                                           admin setting
+     *                                                           (tile-quick-search
+     *                                                           REQ-QSEARCH-004).
      */
     public function __construct(
         IRequest $request,
@@ -97,6 +105,7 @@ public function __construct(
         private readonly RoleFeaturePermissionService $roleFeaturePerm,
         private readonly DashboardTreeService $treeService,
         private readonly LoggerInterface $logger,
+        private readonly AdminSettingsService $adminSettingsService,
     ) {
         parent::__construct(appName: Application::APP_ID, request: $request);
     }//end __construct()
@@ -320,9 +329,18 @@ public function index(string $deepLink=''): TemplateResponse
             );
         }
 
+        // tile-quick-search REQ-QSEARCH-004: read the admin-configured
+        // no-match fallback target. `getSettings()` already resolves the
+        // safe 'none' default when unset/invalid, so this never throws.
+        $quicksearchFallbackTarget = (string) (
+            $this->adminSettingsService->getSettings()['quicksearchFallbackTarget']
+            ?? AdminSettingsService::DEFAULT_QUICKSEARCH_FALLBACK_TARGET
+        );
+
         $builder
             ->setAllowedWidgets($allowedWidgets)
             ->setDeepLinkPath($deepLinkPath)
+            ->setQuicksearchFallbackTarget($quicksearchFallbackTarget)
             ->apply();
 
         // REQ-SHELL-001: pass the chrome slot ids so Nextcloud treats

lib/Db/AdminSetting.php

@@ -213,6 +213,15 @@ class AdminSetting extends Entity implements JsonSerializable
      */
     public const KEY_MAX_WIDGETS_PER_DASHBOARD = AdminSettingKey::MAX_WIDGETS_PER_DASHBOARD->value;
 
+    /**
+     * BC alias for AdminSettingKey::QUICKSEARCH_FALLBACK_TARGET (tile-quick-search).
+     *
+     * @var string
+     *
+     * @see AdminSettingKey::QUICKSEARCH_FALLBACK_TARGET
+     */
+    public const KEY_QUICKSEARCH_FALLBACK_TARGET = AdminSettingKey::QUICKSEARCH_FALLBACK_TARGET->value;
+
     /**
      * The setting key.
      *

lib/Db/AdminSettingKey.php

@@ -16,6 +16,7 @@
  *  - Footer:               FOOTER_ENABLED, FOOTER_HTML, FOOTER_CONFIG,
  *                          FOOTER_BACKGROUND_COLOR, FOOTER_TEXT_COLOR
  *  - Setup wizard:         SETUP_WIZARD_COMPLETE, CONTENT_STORAGE
+ *  - Quick search:         QUICKSEARCH_FALLBACK_TARGET (tile-quick-search)
  *
  * @category Db
  * @package  OCA\LaunchPad\Db
@@ -61,4 +62,5 @@ enum AdminSettingKey: string
     case LEGACY_WIDGET_BRIDGE_ENABLED   = 'legacy_widget_bridge_enabled';
     case MAX_DASHBOARDS_PER_USER        = 'max_dashboards_per_user';
     case MAX_WIDGETS_PER_DASHBOARD      = 'max_widgets_per_dashboard';
+    case QUICKSEARCH_FALLBACK_TARGET    = 'quicksearch_fallback_target';
 }//end enum

lib/Service/AdminSettingsService.php

@@ -100,6 +100,17 @@ public function getSettings(): array
         $maxDashKey   = AdminSetting::KEY_MAX_DASHBOARDS_PER_USER;
         $maxWidgetKey = AdminSetting::KEY_MAX_WIDGETS_PER_DASHBOARD;
 
+        // tile-quick-search REQ-QSEARCH-004: fall back to the safe
+        // 'none' default when unset, OR when a previously-stored value no
+        // longer validates (e.g. an admin-edited DB row) — never surface
+        // a value the frontend can't safely act on.
+        $fallbackKey             = AdminSetting::KEY_QUICKSEARCH_FALLBACK_TARGET;
+        $storedFallbackTarget    = $settings[$fallbackKey] ?? null;
+        $quicksearchFallbackTarget = is_string($storedFallbackTarget) === true
+            && $this->isValidQuicksearchFallbackTarget(value: $storedFallbackTarget) === true
+                ? $storedFallbackTarget
+                : self::DEFAULT_QUICKSEARCH_FALLBACK_TARGET;
+
         return [
             'defaultPermissionLevel'      => $settings[$permKey] ?? $permDef,
             // REQ-ASET-003 (extended): default `false` — admins MUST opt in
@@ -122,6 +133,9 @@ public function getSettings(): array
             // quotas. `0` = unlimited (no enforcement).
             'maxDashboardsPerUser'        => $this->clampQuota(value: $settings[$maxDashKey] ?? 0),
             'maxWidgetsPerDashboard'      => $this->clampQuota(value: $settings[$maxWidgetKey] ?? 0),
+            // tile-quick-search REQ-QSEARCH-004: 'none' | 'unified-search'
+            // | an https URL template containing '{query}'.
+            'quicksearchFallbackTarget'   => $quicksearchFallbackTarget,
         ];
     }//end getSettings()
 
@@ -181,6 +195,83 @@ public function clampQuota(mixed $value): int
      */
     public const VALID_CONTENT_STORAGE_VALUES = ['database', 'groupfolder'];
 
+    /**
+     * tile-quick-search REQ-QSEARCH-004: no-match fallback disabled — Enter
+     * on a zero-match query takes no navigation action.
+     *
+     * @var string
+     */
+    public const QUICKSEARCH_FALLBACK_NONE = 'none';
+
+    /**
+     * tile-quick-search REQ-QSEARCH-004: no-match fallback hands the query
+     * to Nextcloud unified search.
+     *
+     * @var string
+     */
+    public const QUICKSEARCH_FALLBACK_UNIFIED_SEARCH = 'unified-search';
+
+    /**
+     * Default `quicksearch_fallback_target` when no admin setting row
+     * exists — no navigation on no-match Enter (REQ-QSEARCH-004 "No
+     * fallback configured" scenario is the safe out-of-the-box default).
+     *
+     * @var string
+     */
+    public const DEFAULT_QUICKSEARCH_FALLBACK_TARGET = self::QUICKSEARCH_FALLBACK_NONE;
+
+    /**
+     * Validate a `quicksearch_fallback_target` value (REQ-QSEARCH-004
+     * "Fallback template validation" scenario). Valid values are the two
+     * literal targets, or an `https` URL template containing the
+     * `{query}` placeholder.
+     *
+     * @param string|null $value the candidate value.
+     *
+     * @return bool true when `$value` is a valid fallback target.
+     *
+     * @spec openspec/specs/tile-quick-search/spec.md
+     */
+    public function isValidQuicksearchFallbackTarget(?string $value): bool
+    {
+        if ($value === null) {
+            return false;
+        }
+
+        if ($value === self::QUICKSEARCH_FALLBACK_NONE || $value === self::QUICKSEARCH_FALLBACK_UNIFIED_SEARCH) {
+            return true;
+        }
+
+        return $this->isValidQuicksearchFallbackUrlTemplate(value: $value);
+    }//end isValidQuicksearchFallbackTarget()
+
+    /**
+     * Validate the `https` + `{query}`-placeholder shape of a web-search
+     * fallback URL template (REQ-QSEARCH-004). Substitutes a harmless
+     * probe string for `{query}` before validating so a template like
+     * `https://example.org/search?q={query}` — not a valid URL as
+     * written — validates correctly.
+     *
+     * @param string $value the candidate URL template.
+     *
+     * @return bool true when `$value` is a valid `https` URL template
+     *              containing `{query}`.
+     */
+    private function isValidQuicksearchFallbackUrlTemplate(string $value): bool
+    {
+        if (trim($value) === '' || str_contains(haystack: $value, needle: '{query}') === false) {
+            return false;
+        }
+
+        $probe = str_replace(search: '{query}', replace: 'quicksearch-validation-probe', subject: $value);
+
+        if (parse_url(url: $probe, component: PHP_URL_SCHEME) !== 'https') {
+            return false;
+        }
+
+        return filter_var(value: $probe, filter: FILTER_VALIDATE_URL) !== false;
+    }//end isValidQuicksearchFallbackUrlTemplate()
+
     /**
      * Update admin settings.
      *
@@ -220,11 +311,21 @@ public function clampQuota(mixed $value): int
      *                                                 `[0, 10000]`).
      *                                                 dashboard-quota-limits
      *                                                 REQ-QUOTA-001.
+     * @param string|null $quicksearchFallbackTarget   No-match fallback for
+     *                                                 the on-dashboard quick
+     *                                                 search: `'none'`,
+     *                                                 `'unified-search'`, or
+     *                                                 an `https` URL
+     *                                                 template containing
+     *                                                 `{query}`.
+     *                                                 tile-quick-search
+     *                                                 REQ-QSEARCH-004.
      *
      * @return void
      *
-     * @throws \InvalidArgumentException When `$contentStorage` or
-     *                                   `$defaultSharePermissionLevel` is not
+     * @throws \InvalidArgumentException When `$contentStorage`,
+     *                                   `$defaultSharePermissionLevel`, or
+     *                                   `$quicksearchFallbackTarget` is not
      *                                   a valid value.
      *
      * @spec openspec/changes/retrofit-2026-05-24-annotate-launchpad/tasks.md#task-2
@@ -240,7 +341,8 @@ public function updateSettings(
         ?array $forcedShareGroups=null,
         ?bool $legacyWidgetBridgeEnabled=null,
         ?int $maxDashboardsPerUser=null,
-        ?int $maxWidgetsPerDashboard=null
+        ?int $maxWidgetsPerDashboard=null,
+        ?string $quicksearchFallbackTarget=null
     ): void {
         if ($defaultPermLevel !== null) {
             $this->settingMapper->setSetting(
@@ -307,6 +409,22 @@ public function updateSettings(
             );
         }
 
+        // tile-quick-search REQ-QSEARCH-004 "Fallback template validation"
+        // scenario: reject an invalid target at save time rather than
+        // silently storing something the frontend can't act on.
+        if ($quicksearchFallbackTarget !== null) {
+            if ($this->isValidQuicksearchFallbackTarget(value: $quicksearchFallbackTarget) === false) {
+                throw new InvalidArgumentException(
+                    message: "Invalid value for quicksearchFallbackTarget. Must be 'none', 'unified-search', or an https URL template containing '{query}'."
+                );
+            }
+
+            $this->settingMapper->setSetting(
+                key: AdminSetting::KEY_QUICKSEARCH_FALLBACK_TARGET,
+                value: $quicksearchFallbackTarget
+            );
+        }
+
         $this->persistSharingAndBridgeSettings(
             defaultSharePermissionLevel: $defaultSharePermissionLevel,
             forcedShareGroups: $forcedShareGroups,

lib/Service/InitialStateBuilder.php

@@ -332,6 +332,30 @@ public function setDeepLinkPath(string $deepLinkPath): self
         return $this;
     }//end setDeepLinkPath()
 
+    /**
+     * Set the admin-configured quick-search no-match fallback target
+     * (workspace). `'none'` | `'unified-search'` | a validated `https`
+     * URL template containing `{query}`.
+     *
+     * Optional key — mirrors {@see self::setDeepLinkPath()}'s pattern:
+     * NOT in {@see self::REQUIRED_KEYS}, so an older deploy that hasn't
+     * called this setter yet still passes {@see self::apply()}'s
+     * required-key check, and the JS reader's `'none'` default keeps the
+     * frontend typed either way (tile-quick-search REQ-QSEARCH-004).
+     *
+     * @param string $quicksearchFallbackTarget The current fallback-target
+     *                                          setting value.
+     *
+     * @return self Fluent.
+     *
+     * @spec openspec/specs/tile-quick-search/spec.md
+     */
+    public function setQuicksearchFallbackTarget(string $quicksearchFallbackTarget): self
+    {
+        $this->values['quicksearchFallbackTarget'] = $quicksearchFallbackTarget;
+        return $this;
+    }//end setQuicksearchFallbackTarget()
+
     /**
      * Set every Nextcloud group (admin).
      *

…ec/changes/tile-quick-search/proposal.md …2026-07-23-tile-quick-search/proposal.mdopenspec/changes/tile-quick-search/proposal.md renamed to openspec/changes/archive/2026-07-23-tile-quick-search/proposal.md openspec/changes/tile-quick-search/proposal.md renamed to openspec/changes/archive/2026-07-23-tile-quick-search/proposal.md

@@ -0,0 +1,27 @@
+# Tasks: On-dashboard quick-search / launcher bar
+
+## Backend
+- [~] Add app config `quicksearch_fallback_target` (`none` / `unified-search` / web-search URL template) with an admin default and a per-user override. **Admin default DONE** (`AdminSettingKey::QUICKSEARCH_FALLBACK_TARGET`, `AdminSettingsService::getSettings()`/`updateSettings()`, `AdminController::getSettings()`/`updateSettings()` — no new route, existing endpoint extended). **Per-user override NOT implemented** — the setting is currently admin/instance-wide only.
+- [x] Provide `quicksearch_fallback_target` to the frontend via `IInitialState::provideInitialState()` (no new controller/endpoint). `InitialStateBuilder::setQuicksearchFallbackTarget()` (optional key, mirrors `deepLinkPath`) + `PageController::index()` wiring.
+- [x] Validate a web-search URL template on save (must be `https`, must contain the `{query}` placeholder); reject otherwise. `AdminSettingsService::isValidQuicksearchFallbackTarget()` / `isValidQuicksearchFallbackUrlTemplate()`, enforced in `updateSettings()` (throws `InvalidArgumentException` → HTTP 400 via the existing `AdminController::updateSettings()` catch block).
+
+## Frontend
+- [x] `src/composables/useTileSearch.js` — filter+rank the reactive tile list by query, track active-selection index, own global keydown listeners (`/`, `Ctrl+K`, arrows, Enter, Esc), and decide the no-match fallback route. (Global-listener *attachment* lives in `RuntimeShellSearch.vue`'s mounted/beforeDestroy per Vue idiom in this codebase; the composable owns the pure shortcut/ranking/fallback *decisions*, unit-tested independently of any DOM.)
+- [x] `src/components/RuntimeShellSearch.vue` — labelled search input (`role="search"`), result/selection affordance, WCAG AA keyboard handling and `aria-activedescendant`, no-match fallback affordance.
+- [x] Mount `RuntimeShellSearch` in the runtime-shell page component; wire `filter`/`open` events to dim non-matching tiles, scroll-to and activate the selected tile. (`WorkspaceApp.vue`; DOM reach into the sibling `Views.vue` grid via `data-placement-id` + a plain `querySelector`, since the grid lives in a different component's tree.)
+- [x] Read `quicksearch_fallback_target` via `loadState` from `@nextcloud/initial-state`; dispatch to NC unified search (existing `nc-unified-search-integration`) or open the web-search template on no-match Enter. Web-search: `window.open(...)`. Unified-search: best-effort `window.dispatchEvent(new CustomEvent('nextcloud:unified-search.search', {detail:{query}}))` — no documented public JS API to open NC's unified-search UI programmatically was found in this repo's `@nextcloud/*` dependencies, so this dispatches a plausible hook a listener could pick up without navigating on its own (satisfies the "MUST NOT navigate away on its own" clause either way).
+
+## Testing
+- [x] Vitest: `useTileSearch` filtering/ranking (prefix > substring > subsequence), selection wrap-around, Esc-clear, no-match fallback decision per config. 57 tests in `useTileSearch.spec.js`.
+- [x] Vitest: URL-template validation (https + `{query}` required). Covered on both sides: `useTileSearch.spec.js` (`isValidFallbackTemplate`/`resolveFallbackAction`) and PHP `AdminSettingsServiceTest.php` (`isValidQuicksearchFallbackTarget`, data-provider covering valid/invalid templates).
+- [ ] Playwright: type to filter tiles live; arrow + Enter opens the selected tile; Esc clears; `/` and `Ctrl+K` focus the bar. **Not run** — task instructions restricted this build to local unit tests only (no Playwright/e2e against the live instance).
+- [ ] Playwright/axe: search bar labelled, focus visible, active result exposed via `aria-activedescendant`. **Not run**, same reason. ARIA structure is covered by Vitest component tests instead (role/attribute assertions), which is a partial substitute but not a real axe audit.
+
+## Docs
+- [ ] Add a "Quick search" section to the dashboard-viewing docs; document the `/` and `Ctrl+K` shortcuts and the fallback-target setting.
+
+## Out of scope (follow-ups)
+- Cross-dashboard global search — `quicksearch-global`.
+- Search over live-tile values / widget contents — `quicksearch-content`.
+- Recent/suggested query history — no query is stored.
+- Server-side ranking / autocomplete endpoint.