@vicacha-devs/strapi-plugin-global-search 0.0.0-stage → 2.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sagar Maurya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# `@vicacha-devs/strapi-plugin-global-search`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@vicacha-devs/strapi-plugin-global-search.svg)](https://www.npmjs.com/package/@vicacha-devs/strapi-plugin-global-search)
+[![Strapi 5](https://img.shields.io/badge/strapi-v5-blue)](https://strapi.io)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Spotlight-style **global search** for the Strapi v5 admin: every collection type and single type, from a dedicated page or a <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>K</kbd> palette.
+
+Install it, enable it, and start Strapi. It introspects your content types at boot and never needs to know your schema ahead of time.
+
+**Strapi 4:** use [`strapi-global-search@1.x`](https://www.npmjs.com/package/strapi-global-search/v/1.0.0). This major (`2.x`) is Strapi 5 only.
+
+## Features
+
+- **Searches everything** — every `api::` and Content-Manager-visible `plugin::` collection type _and_ single type, including custom fields, structured rich text (ProseMirror / Tiptap JSON), and text fields nested inside components.
+- **Two surfaces** — a full search page under the plugins menu, and an instant SPA-navigating command palette (<kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>K</kbd>) available from anywhere in the admin.
+- **Predictable ordering** — results are ranked id → name → other fields → nested fields (see below), never by an opaque relevance score.
+- **Respects your permissions** — an editor only ever sees content types they can read in the Content Manager.
+- **i18n and draft/publish aware** — searches every locale by default and finds drafts. Includes UI translations for `en`, `fr`, `es`, `ar`, and `tr`.
+- **No index, no extra services** — plain database queries, nothing to keep in sync.
+
+## Installation
+
+```bash
+pnpm add @vicacha-devs/strapi-plugin-global-search
+# or
+npm install @vicacha-devs/strapi-plugin-global-search
+```
+
+Enable it in `config/plugins.js` or `config/plugins.ts`:
+
+```js
+module.exports = {
+	"global-search": {
+		enabled: true,
+	},
+};
+```
+
+Then start your Strapi app (`npm run develop`). There is no extra build step.
+
+This package has **no** `preinstall` / `install` / `postinstall` scripts and does not use git or remote URL dependencies. On [npm v12](https://github.blog/changelog/2026-07-08-npm-install-time-security-and-gat-bypass2fa-deprecation/) you do not need an `allowScripts` entry for `strapi-global-search`.
+
+## Result ordering
+
+| Priority | Match                                       |
+| -------- | ------------------------------------------- |
+| 1        | `id` / `documentId` exact                   |
+| 2        | `id` / `documentId` partial                 |
+| 3        | Name (the Content Manager main field) exact |
+| 4        | Name starts with the query                  |
+| 5        | Name contains the query                     |
+| 6        | Any other top-level text field              |
+| 7        | Any text field inside a component           |
+
+Ties break on an exact-case match, then the shortest matching value, then the most recently updated entry.
+
+## Spotlight Command Palette (<kbd>Cmd</kbd>/<kbd>Ctrl</kbd> + <kbd>K</kbd>)
+
+At bootstrap, the plugin mounts a lightweight React portal (`#global-search-portal-root`) on `document.body` so the command palette can be opened on **any** Strapi v5 Admin route — including inside Content Manager edit views and Settings pages:
+
+| Shortcut | Action |
+| :--- | :--- |
+| <kbd>⌘</kbd> + <kbd>K</kbd> / <kbd>Ctrl</kbd> + <kbd>K</kbd> | Toggle the Spotlight Command Palette from anywhere in the Strapi v5 Admin panel |
+| <kbd>↑</kbd> / <kbd>↓</kbd> | Navigate up and down through ranked search results |
+| <kbd>↵</kbd> (`Enter`) | Open the highlighted entry in the current tab via SPA router navigation |
+| <kbd>⌘</kbd>/<kbd>Ctrl</kbd> + <kbd>↵</kbd> | Open the highlighted entry in a new browser tab |
+| <kbd>Esc</kbd> | Close the command palette and restore focus |
+
+Each result row displays:
+- **Entry Title & Highlighted Match** — matched query substrings are highlighted inline across both the main field and matched secondary/component fields (e.g., `Slug: historia-del-islam`).
+- **Document ID Badge** — quick reference to the Strapi v5 `documentId` (`#ikm8b47sijmgzv99g119h3a5`).
+- **Locale & Publication State Badges** — shows the active i18n locale (`en`, `es`, `ar`, `tr`) and `DRAFT` / `PUBLISHED` status alongside the human-readable Content-Type label (`Article & Course`, `Community Service`, `Resource Publication`).
+
+## Configuration
+
+Everything is optional and can be changed at **Settings → Global Search → Configuration**, or pinned in `config/plugins.js` / `config/plugins.ts`:
+
+```js
+module.exports = {
+	"global-search": {
+		enabled: true,
+		config: {
+			minChars: 2, // minimum query length
+			debounce: 250, // ms to wait after the last keystroke
+			perTypeLimit: 20, // rows fetched per content type
+			maxResults: 100, // cap on the merged, ranked result set
+			deep: true, // search inside components
+			maxDepth: 3, // how many component levels to walk
+			includeDrafts: true, // include unpublished entries
+			includePluginContentTypes: true, // include visible plugin::* content types
+			queryTimeout: 4000, // per-content-type timeout in ms
+			concurrency: 8, // content types queried in parallel
+			excludedContentTypes: [], // e.g. ['api::log.log']
+			excludedFields: [], // e.g. ['api::article.article:body']
+			displayFields: {}, // extra fields in the result row, keyed by UID
+		},
+	},
+};
+```
+
+## Permissions
+
+Two RBAC actions are registered and can be assigned per role:
+
+- `plugin::global-search.read` — use the search page and the palette.
+- `plugin::global-search.settings` — change the configuration.
+
+Search results are additionally filtered by each user's Content Manager read permissions.
+
+## Performance notes
+
+Searching runs live database `LIKE` queries — there is no index to maintain, but a query on a very large table is only as fast as your database makes it. The plugin keeps this bounded with a per-content-type row limit, a bounded column projection, a per-type timeout, a concurrency cap and a client-side debounce. For very large tables, consider a database index on the fields people actually search, or disable those content types in Settings.
+
+Reported result counts reflect the capped set (`perTypeLimit` rows per type, `maxResults` overall) — a `+` in the UI means there were more matches than were fetched.
+
+## Limitations
+
+- **Dynamic zones** and **blocks** fields are not searched: the query engine cannot filter polymorphic JSON columns.
+- Relations, media and raw JSON fields are not searched.
+- Internal Strapi system plugin content types (such as `plugin::upload.file`, `plugin::i18n.locale`, and `plugin::users-permissions.*`) are skipped automatically.
+
+## Compatibility
+
+|        |                                     |
+| ------ | ----------------------------------- |
+| Strapi | `^5.0.0` (developed against 5.52.0) |
+| Node   | 20 – 26                             |
+| React  | 18                                  |
+
+## Publishing and supply chain
+
+Public releases are published from GitHub Actions with [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC). There is no long-lived 2FA-bypass granular access token. See [npm install-time security and GAT bypass2fa deprecation](https://github.blog/changelog/2026-07-08-npm-install-time-security-and-gat-bypass2fa-deprecation/).
+
+## License
+
+MIT

package/dist/admin/index.d.ts

@@ -0,0 +1,2 @@
+declare const plugin: Record<string, unknown>;
+export default plugin;