create-nextblock 0.14.1 → 0.14.4

package/templates/nextblock-template/docs/13-STAYING-UP-TO-DATE.md

@@ -1,151 +1,151 @@
-# 13 · Staying Up to Date (Automated Upstream Updates)
-
-NextBlock keeps your instance in sync with the upstream project
-(`nextblock-cms/nextblock`) with **as little manual work as possible**. How updates
-arrive depends on how you deployed, and the system auto-detects which path applies:
-
-| Install type | Track | How updates arrive |
-| :--- | :--- | :--- |
-| Vercel 1-click / GitHub fork (git-backed) | **A** | A daily GitHub Action merges upstream and pushes to your deploy branch (→ Vercel CD). |
-| `npm create nextblock` / local clone / Docker image (standalone) | **B** | The CMS checks GitHub Releases and shows a "download the new version" banner. |
-
-Both tracks surface their status in the CMS through a dashboard banner backed by the
-`system_alerts` table (migration `00000000000036`). Reads are ADMIN-only (RLS).
-
----
-
-## Track A — Git-backed installs (Vercel 1-click, GitHub forks)
-
-The workflow lives at [`.github/workflows/nextblock-sync.yml`](../.github/workflows/nextblock-sync.yml).
-It runs **daily at 00:00 UTC** and on demand (**Actions → NextBlock Upstream Sync → Run
-workflow**). Each run:
-
-1. Merges the upstream release branch into your deploy branch.
-2. **Clean merge** → commits and pushes to your branch, which triggers a normal Vercel
-   deployment. Any open conflict issue is auto-closed.
-3. **Conflict** → aborts the merge and opens (or updates) a GitHub Issue labeled
-   `nextblock-sync-conflict`. The CMS mirrors that issue into an **amber banner** on the
-   dashboard with a link to resolve it. Once you resolve and **close the issue**, the
-   banner clears automatically.
-
-### One-click install (Connect GitHub)
-
-Vercel's 1-click deploy creates your repo through an integration whose token lacks the
-GitHub **`workflow`** scope, so GitHub **strips `.github/workflows/`** from the copy — your
-new repo won't have the sync workflow even though the template ships it. To fix that with no
-token to create, the dashboard onboarding step shows a **Connect GitHub** button:
-
-1. Click **Connect GitHub** — a short code appears.
-2. Click **Authorize on GitHub**, enter the code, approve.
-3. NextBlock installs `.github/workflows/nextblock-sync.yml` into your repo for you, and the
-   step turns green.
-
-This uses GitHub's **device flow** — no token to create, no per-site callback, nothing to
-configure (the public client id ships with NextBlock). The authorization requests the
-`repo` + `workflow` scopes because GitHub requires them to write a workflow file; NextBlock
-uses the grant once to install the file and does **not** store it. Revoke it anytime at
-GitHub → **Settings → Applications**.
-
-### Do you need to enable GitHub Actions?
-
-It depends on how the repository was created:
-
-- **Vercel 1-click deploy** creates a **new repository you own** (a copy, *not* a GitHub
-  fork). GitHub **enables Actions by default** on repos you own — **there's nothing to turn
-  on**. The sync workflow runs automatically once it lands on your repo's **default branch**.
-- **A manual GitHub _fork_** (the "Fork" button) has Actions **disabled** by default. Enable
-  them once: your repo → **Actions** tab → **"I understand my workflows, go ahead and enable
-  them."**
-
-> **Seeing GitHub's "Get started with Actions / choose a workflow" page?** That only means
-> your Actions tab is **empty** — `.github/workflows/nextblock-sync.yml` isn't on your
-> **default branch** yet (scheduled workflows only run from the default branch). Once it is,
-> the tab shows **NextBlock Upstream Sync** with a **Run workflow** button. There is no
-> separate "enable" button on an owned repo because Actions are already on.
-
-The dashboard onboarding step ("Automatic updates (GitHub Actions)") links to **Settings →
-Actions** — where you can confirm Actions are allowed — and completes itself once GitHub
-reports the sync workflow as active.
-
-### No GitHub secrets required (public forks)
-
-The conflict signal uses the **`GITHUB_TOKEN` that GitHub provides to every workflow
-automatically** — you do **not** add any Supabase secret to GitHub. The app writes the
-dashboard alert itself using the Supabase key it already has, and reads your repo's
-conflict issues over the public GitHub API.
-
-> **We recommend forking to a _public_ repository** — it's fully zero-config.
-
-### Private forks
-
-If your fork is **private**, the public GitHub API can't read its issues, so add **one**
-environment variable to your deployment (Vercel project → Settings → Environment
-Variables, or your `.env`):
-
-| Variable | Value |
-| :--- | :--- |
-| `NEXTBLOCK_GITHUB_TOKEN` | A GitHub token with **read access to issues** on your fork (a fine-grained PAT scoped to the repo, or a classic token with `repo`). |
-
-With that set, the dashboard conflict banner works on private forks too. (The workflow
-itself still needs no extra secret — `GITHUB_TOKEN` covers it either way.)
-
-> **⚠️ Vercel Hobby (free) plan + a private repo blocks auto-deploys.** On Hobby, Vercel only
-> deploys **private**-repo commits authored by the project owner and rejects automated
-> (bot/collaborator) commits — so the auto-merge push won't deploy (*"Hobby Plan does not
-> support collaboration for private repositories"*). Either **make the repo public**
-> (recommended — it also makes the conflict banner tokenless) or upgrade to **Vercel Pro**.
-> Public repos have no such restriction on Hobby.
-
-### How the dashboard stays current (no cron)
-
-The CMS refreshes update/conflict status **in the background after a dashboard page
-loads** (throttled to ~6 hours), so it works on Vercel's Hobby plan without consuming a
-cron slot. Admins can also force a check immediately:
-
-```
-POST /api/cms/check-updates      # admin-only; returns the version + conflict status
-```
-
----
-
-## Track B — Standalone installs (npm create / local / Docker)
-
-These installs aren't wired to a GitHub Action, so NextBlock checks the **GitHub Releases
-API** and, when a newer release exists, records a `runtime_update_available` alert — an
-**indigo banner** on the dashboard with a direct **download link** to the release tarball.
-Updating is manual by design: download the archive, replace your files, and update
-dependencies (`npm install`). The same admin check endpoint above triggers a check on
-demand.
-
----
-
-## Schema stays in step with deploys (build-time migrations)
-
-So a new version's code never runs against an old schema, a build-time hook
-([`apps/nextblock/tools/build-migrate.mjs`](../apps/nextblock/tools/build-migrate.mjs))
-applies pending, forward-only migrations **before** `next build`:
-
-- **Vercel:** runs automatically when `VERCEL_ENV=production`; **preview/development
-  builds are skipped** so they never touch live data.
-- **Standalone / local / Docker:** gated on `NEXTBLOCK_BUILD_MIGRATE=1`, which the
-  `/setup` wizard and the create/Docker setup scripts write into your env automatically.
-
-It is **non-destructive and never breaks the build** — if the database is unreachable it
-logs a warning and continues. Migrations are tracked in `supabase_migrations.schema_migrations`,
-identically to the Supabase CLI.
-
-> **Edge case:** if your project's migration history is empty/inconsistent, the hook skips
-> rather than risk misapplying. Run `npm run db:migrate:repair-history` then
-> `npm run db:migrate` once to reconcile (see [docs/04](./04-DATABASE-AND-AUTH.md)).
-
----
-
-## Quick reference
-
-| You want… | Do this |
-| :--- | :--- |
-| Fully hands-off updates | Fork **public**, deploy on Vercel, **enable Actions** once. |
-| Conflict banners on a **private** fork | Also set `NEXTBLOCK_GITHUB_TOKEN`. |
-| To update a **standalone** install | Watch for the dashboard banner → download → replace → `npm install`. |
-| To force an update check now | Dashboard (admin) → it polls in the background; or `POST /api/cms/check-updates`. |
-| To resolve a sync conflict | Open the linked GitHub issue, merge upstream locally, fix, push, close the issue. |
+# 13 · Staying Up to Date (Automated Upstream Updates)
+
+NextBlock keeps your instance in sync with the upstream project
+(`nextblock-cms/nextblock`) with **as little manual work as possible**. How updates
+arrive depends on how you deployed, and the system auto-detects which path applies:
+
+| Install type | Track | How updates arrive |
+| :--- | :--- | :--- |
+| Vercel 1-click / GitHub fork (git-backed) | **A** | A daily GitHub Action merges upstream and pushes to your deploy branch (→ Vercel CD). |
+| `npm create nextblock` / local clone / Docker image (standalone) | **B** | The CMS checks GitHub Releases and shows a "download the new version" banner. |
+
+Both tracks surface their status in the CMS through a dashboard banner backed by the
+`system_alerts` table (migration `00000000000036`). Reads are ADMIN-only (RLS).
+
+---
+
+## Track A — Git-backed installs (Vercel 1-click, GitHub forks)
+
+The workflow lives at [`.github/workflows/nextblock-sync.yml`](../.github/workflows/nextblock-sync.yml).
+It runs **daily at 00:00 UTC** and on demand (**Actions → NextBlock Upstream Sync → Run
+workflow**). Each run:
+
+1. Merges the upstream release branch into your deploy branch.
+2. **Clean merge** → commits and pushes to your branch, which triggers a normal Vercel
+   deployment. Any open conflict issue is auto-closed.
+3. **Conflict** → aborts the merge and opens (or updates) a GitHub Issue labeled
+   `nextblock-sync-conflict`. The CMS mirrors that issue into an **amber banner** on the
+   dashboard with a link to resolve it. Once you resolve and **close the issue**, the
+   banner clears automatically.
+
+### One-click install (Connect GitHub)
+
+Vercel's 1-click deploy creates your repo through an integration whose token lacks the
+GitHub **`workflow`** scope, so GitHub **strips `.github/workflows/`** from the copy — your
+new repo won't have the sync workflow even though the template ships it. To fix that with no
+token to create, the dashboard onboarding step shows a **Connect GitHub** button:
+
+1. Click **Connect GitHub** — a short code appears.
+2. Click **Authorize on GitHub**, enter the code, approve.
+3. NextBlock installs `.github/workflows/nextblock-sync.yml` into your repo for you, and the
+   step turns green.
+
+This uses GitHub's **device flow** — no token to create, no per-site callback, nothing to
+configure (the public client id ships with NextBlock). The authorization requests the
+`repo` + `workflow` scopes because GitHub requires them to write a workflow file; NextBlock
+uses the grant once to install the file and does **not** store it. Revoke it anytime at
+GitHub → **Settings → Applications**.
+
+### Do you need to enable GitHub Actions?
+
+It depends on how the repository was created:
+
+- **Vercel 1-click deploy** creates a **new repository you own** (a copy, *not* a GitHub
+  fork). GitHub **enables Actions by default** on repos you own — **there's nothing to turn
+  on**. The sync workflow runs automatically once it lands on your repo's **default branch**.
+- **A manual GitHub _fork_** (the "Fork" button) has Actions **disabled** by default. Enable
+  them once: your repo → **Actions** tab → **"I understand my workflows, go ahead and enable
+  them."**
+
+> **Seeing GitHub's "Get started with Actions / choose a workflow" page?** That only means
+> your Actions tab is **empty** — `.github/workflows/nextblock-sync.yml` isn't on your
+> **default branch** yet (scheduled workflows only run from the default branch). Once it is,
+> the tab shows **NextBlock Upstream Sync** with a **Run workflow** button. There is no
+> separate "enable" button on an owned repo because Actions are already on.
+
+The dashboard onboarding step ("Automatic updates (GitHub Actions)") links to **Settings →
+Actions** — where you can confirm Actions are allowed — and completes itself once GitHub
+reports the sync workflow as active.
+
+### No GitHub secrets required (public forks)
+
+The conflict signal uses the **`GITHUB_TOKEN` that GitHub provides to every workflow
+automatically** — you do **not** add any Supabase secret to GitHub. The app writes the
+dashboard alert itself using the Supabase key it already has, and reads your repo's
+conflict issues over the public GitHub API.
+
+> **We recommend forking to a _public_ repository** — it's fully zero-config.
+
+### Private forks
+
+If your fork is **private**, the public GitHub API can't read its issues, so add **one**
+environment variable to your deployment (Vercel project → Settings → Environment
+Variables, or your `.env`):
+
+| Variable | Value |
+| :--- | :--- |
+| `NEXTBLOCK_GITHUB_TOKEN` | A GitHub token with **read access to issues** on your fork (a fine-grained PAT scoped to the repo, or a classic token with `repo`). |
+
+With that set, the dashboard conflict banner works on private forks too. (The workflow
+itself still needs no extra secret — `GITHUB_TOKEN` covers it either way.)
+
+> **⚠️ Vercel Hobby (free) plan + a private repo blocks auto-deploys.** On Hobby, Vercel only
+> deploys **private**-repo commits authored by the project owner and rejects automated
+> (bot/collaborator) commits — so the auto-merge push won't deploy (*"Hobby Plan does not
+> support collaboration for private repositories"*). Either **make the repo public**
+> (recommended — it also makes the conflict banner tokenless) or upgrade to **Vercel Pro**.
+> Public repos have no such restriction on Hobby.
+
+### How the dashboard stays current (no cron)
+
+The CMS refreshes update/conflict status **in the background after a dashboard page
+loads** (throttled to ~6 hours), so it works on Vercel's Hobby plan without consuming a
+cron slot. Admins can also force a check immediately:
+
+```
+POST /api/cms/check-updates      # admin-only; returns the version + conflict status
+```
+
+---
+
+## Track B — Standalone installs (npm create / local / Docker)
+
+These installs aren't wired to a GitHub Action, so NextBlock checks the **GitHub Releases
+API** and, when a newer release exists, records a `runtime_update_available` alert — an
+**indigo banner** on the dashboard with a direct **download link** to the release tarball.
+Updating is manual by design: download the archive, replace your files, and update
+dependencies (`npm install`). The same admin check endpoint above triggers a check on
+demand.
+
+---
+
+## Schema stays in step with deploys (build-time migrations)
+
+So a new version's code never runs against an old schema, a build-time hook
+([`apps/nextblock/tools/build-migrate.mjs`](../apps/nextblock/tools/build-migrate.mjs))
+applies pending, forward-only migrations **before** `next build`:
+
+- **Vercel:** runs automatically when `VERCEL_ENV=production`; **preview/development
+  builds are skipped** so they never touch live data.
+- **Standalone / local / Docker:** gated on `NEXTBLOCK_BUILD_MIGRATE=1`, which the
+  `/setup` wizard and the create/Docker setup scripts write into your env automatically.
+
+It is **non-destructive and never breaks the build** — if the database is unreachable it
+logs a warning and continues. Migrations are tracked in `supabase_migrations.schema_migrations`,
+identically to the Supabase CLI.
+
+> **Edge case:** if your project's migration history is empty/inconsistent, the hook skips
+> rather than risk misapplying. Run `npm run db:migrate:repair-history` then
+> `npm run db:migrate` once to reconcile (see [docs/04](./04-DATABASE-AND-AUTH.md)).
+
+---
+
+## Quick reference
+
+| You want… | Do this |
+| :--- | :--- |
+| Fully hands-off updates | Fork **public**, deploy on Vercel, **enable Actions** once. |
+| Conflict banners on a **private** fork | Also set `NEXTBLOCK_GITHUB_TOKEN`. |
+| To update a **standalone** install | Watch for the dashboard banner → download → replace → `npm install`. |
+| To force an update check now | Dashboard (admin) → it polls in the background; or `POST /api/cms/check-updates`. |
+| To resolve a sync conflict | Open the linked GitHub issue, merge upstream locally, fix, push, close the issue. |

package/templates/nextblock-template/docs/README.md

@@ -1,39 +1,39 @@
-# NextBlock CMS Documentation
-
-This folder is the source-of-truth reference set for the NextBlock monorepo.
-The numbered files are written from live code, routes, migrations, and shipped
-library surfaces rather than historical planning notes.
-
-## Start Here
-
-- Product and architecture overview: [01-PROJECT-OVERVIEW.md](./01-PROJECT-OVERVIEW.md)
-- Commerce capabilities: [02-ECOMMERCE-CAPABILITIES.md](./02-ECOMMERCE-CAPABILITIES.md)
-- CMS editor and block system: [03-CMS-AND-EDITOR.md](./03-CMS-AND-EDITOR.md)
-- Database, auth, and migrations: [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md)
-- Contributor workflow and local operations: [05-DEVELOPER-GUIDE.md](./05-DEVELOPER-GUIDE.md)
-- CLI and scaffolded project flow: [06-CLI-AND-SCAFFOLDING.md](./06-CLI-AND-SCAFFOLDING.md)
-- Block SDK and extensibility surface: [07-BLOCK-SDK-AND-EXTENSIBILITY.md](./07-BLOCK-SDK-AND-EXTENSIBILITY.md)
-- Cortex AI architecture: [08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md](./08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md)
-- Live draft (visual editing) mode: [09-LIVE-DRAFT-MODE.md](./09-LIVE-DRAFT-MODE.md)
-- Custom blocks (data-driven CRUD): [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)
-- Self-hosted local Docker stack: [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md)
-- One-click cloud deploy (Deploy to Vercel): [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md)
-
-## Audience Guide
-
-- New contributors: read `01`, then `04`, then `05`.
-- Commerce work: read `02`, then `04`.
-- Editor or page-builder work: read `03`, then `07`.
-- Custom block work: read `03`, then `10`.
-- AI / Cortex work: read `08`.
-- CLI or template work: read `06`.
-- Publishing the libraries / scaffold CLI: read `06`.
-- Running everything locally without cloud accounts: read `11`.
-- One-click cloud deploy and the browser setup wizard: read `12`.
-- AI agents: start with this index, then move directly to the subsystem file that
-  matches the task. Treat `apps/nextblock`, `libs/*`, and
-  `libs/db/src/supabase/migrations` as the final authority if a doc and code ever
-  disagree.
-- AI agents touching migrations must also read the root `AGENTS.md` note:
-  production/shared database changes are append-only and non-destructive by
-  default.
+# NextBlock CMS Documentation
+
+This folder is the source-of-truth reference set for the NextBlock monorepo.
+The numbered files are written from live code, routes, migrations, and shipped
+library surfaces rather than historical planning notes.
+
+## Start Here
+
+- Product and architecture overview: [01-PROJECT-OVERVIEW.md](./01-PROJECT-OVERVIEW.md)
+- Commerce capabilities: [02-ECOMMERCE-CAPABILITIES.md](./02-ECOMMERCE-CAPABILITIES.md)
+- CMS editor and block system: [03-CMS-AND-EDITOR.md](./03-CMS-AND-EDITOR.md)
+- Database, auth, and migrations: [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md)
+- Contributor workflow and local operations: [05-DEVELOPER-GUIDE.md](./05-DEVELOPER-GUIDE.md)
+- CLI and scaffolded project flow: [06-CLI-AND-SCAFFOLDING.md](./06-CLI-AND-SCAFFOLDING.md)
+- Block SDK and extensibility surface: [07-BLOCK-SDK-AND-EXTENSIBILITY.md](./07-BLOCK-SDK-AND-EXTENSIBILITY.md)
+- Cortex AI architecture: [08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md](./08-NEXTBLOCK-CORTEX-AI-ARCHITECTURE.md)
+- Live draft (visual editing) mode: [09-LIVE-DRAFT-MODE.md](./09-LIVE-DRAFT-MODE.md)
+- Custom blocks (data-driven CRUD): [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)
+- Self-hosted local Docker stack: [11-SELF-HOSTED-DOCKER.md](./11-SELF-HOSTED-DOCKER.md)
+- One-click cloud deploy (Deploy to Vercel): [12-VERCEL-DEPLOYMENT.md](./12-VERCEL-DEPLOYMENT.md)
+
+## Audience Guide
+
+- New contributors: read `01`, then `04`, then `05`.
+- Commerce work: read `02`, then `04`.
+- Editor or page-builder work: read `03`, then `07`.
+- Custom block work: read `03`, then `10`.
+- AI / Cortex work: read `08`.
+- CLI or template work: read `06`.
+- Publishing the libraries / scaffold CLI: read `06`.
+- Running everything locally without cloud accounts: read `11`.
+- One-click cloud deploy and the browser setup wizard: read `12`.
+- AI agents: start with this index, then move directly to the subsystem file that
+  matches the task. Treat `apps/nextblock`, `libs/*`, and
+  `libs/db/src/supabase/migrations` as the final authority if a doc and code ever
+  disagree.
+- AI agents touching migrations must also read the root `AGENTS.md` note:
+  production/shared database changes are append-only and non-destructive by
+  default.

package/templates/nextblock-template/hooks/use-hotkeys.ts

@@ -1,4 +1,4 @@
-import { useEffect, type DependencyList } from 'react';
+import { useEffect, type DependencyList } from 'react';
 
 /**
  * Hook to handle keyboard shortcuts.
@@ -8,26 +8,26 @@ import { useEffect, type DependencyList } from 'react';
  * @param callback The function to call when the key combination is pressed
  * @param deps Dependencies array for the effect
  */
-export function useHotkeys(
-  key: string,
-  callback: (event: KeyboardEvent) => void,
-  deps: DependencyList = [],
-) {
-  useEffect(() => {
-    const normalizedShortcut = key.toLowerCase();
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      const isCtrl = event.ctrlKey || event.metaKey; // cmd on mac, ctrl on windows
-      const keyLower = typeof event.key === 'string' ? event.key.toLowerCase() : '';
-      const isSaveKey = keyLower === 's' || event.code === 'KeyS';
-
-      // Check for ctrl+s / cmd+s
-      if ((normalizedShortcut === 'ctrl+s' || normalizedShortcut === 'meta+s') && isCtrl && isSaveKey) {
-        event.preventDefault();
-        callback(event);
-      }
-    };
-
+export function useHotkeys(
+  key: string,
+  callback: (event: KeyboardEvent) => void,
+  deps: DependencyList = [],
+) {
+  useEffect(() => {
+    const normalizedShortcut = key.toLowerCase();
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const isCtrl = event.ctrlKey || event.metaKey; // cmd on mac, ctrl on windows
+      const keyLower = typeof event.key === 'string' ? event.key.toLowerCase() : '';
+      const isSaveKey = keyLower === 's' || event.code === 'KeyS';
+
+      // Check for ctrl+s / cmd+s
+      if ((normalizedShortcut === 'ctrl+s' || normalizedShortcut === 'meta+s') && isCtrl && isSaveKey) {
+        event.preventDefault();
+        callback(event);
+      }
+    };
+
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
   }, [key, ...deps]); // callback should be stable or included in deps if handled by caller

package/templates/nextblock-template/hooks/useGlobalSearch.ts

@@ -1,101 +1,101 @@
-'use client';
-
-import { useEffect, useMemo, useState } from 'react';
-import { useLanguage } from '../context/LanguageContext';
-import type {
-  GlobalSearchFilter,
-  GlobalSearchResponse,
-  GlobalSearchResult,
-} from '../lib/search/types';
-
-type SearchStatus = 'idle' | 'loading' | 'success' | 'error';
-
-export function useGlobalSearch({
-  initialQuery = '',
-  initialFilter = 'all',
-  limit = 12,
-}: {
-  initialQuery?: string;
-  initialFilter?: GlobalSearchFilter;
-  limit?: number;
-} = {}) {
-  const { currentLocale } = useLanguage();
-  const [query, setQuery] = useState(initialQuery);
-  const [filter, setFilter] = useState<GlobalSearchFilter>(initialFilter);
-  const [results, setResults] = useState<GlobalSearchResult[]>([]);
-  const [counts, setCounts] = useState<GlobalSearchResponse['counts']>({
-    all: 0,
-    page: 0,
-    post: 0,
-    product: 0,
-  });
-  const [status, setStatus] = useState<SearchStatus>('idle');
-
-  const normalizedQuery = useMemo(() => query.replace(/\s+/g, ' ').trim(), [query]);
-  const canSearch = normalizedQuery.length >= 2;
-
-  useEffect(() => {
-    if (!canSearch) {
-      setResults([]);
-      setCounts({ all: 0, page: 0, post: 0, product: 0 });
-      setStatus('idle');
-      return;
-    }
-
-    const controller = new AbortController();
-    const timeoutId = window.setTimeout(async () => {
-      setStatus('loading');
-
-      const params = new URLSearchParams({
-        q: normalizedQuery,
-        type: filter,
-        limit: String(limit),
-      });
-
-      if (currentLocale) {
-        params.set('locale', currentLocale);
-      }
-
-      try {
-        const response = await fetch(`/api/search?${params.toString()}`, {
-          signal: controller.signal,
-        });
-
-        if (!response.ok) {
-          throw new Error(`Search request failed with ${response.status}`);
-        }
-
-        const payload = (await response.json()) as GlobalSearchResponse;
-        setResults(payload.results);
-        setCounts(payload.counts);
-        setStatus('success');
-      } catch (error) {
-        if ((error as Error).name === 'AbortError') {
-          return;
-        }
-
-        console.error('Global search request failed:', error);
-        setResults([]);
-        setCounts({ all: 0, page: 0, post: 0, product: 0 });
-        setStatus('error');
-      }
-    }, 180);
-
-    return () => {
-      controller.abort();
-      window.clearTimeout(timeoutId);
-    };
-  }, [canSearch, currentLocale, filter, limit, normalizedQuery]);
-
-  return {
-    query,
-    setQuery,
-    filter,
-    setFilter,
-    results,
-    counts,
-    status,
-    canSearch,
-    isLoading: status === 'loading',
-  };
-}
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import { useLanguage } from '../context/LanguageContext';
+import type {
+  GlobalSearchFilter,
+  GlobalSearchResponse,
+  GlobalSearchResult,
+} from '../lib/search/types';
+
+type SearchStatus = 'idle' | 'loading' | 'success' | 'error';
+
+export function useGlobalSearch({
+  initialQuery = '',
+  initialFilter = 'all',
+  limit = 12,
+}: {
+  initialQuery?: string;
+  initialFilter?: GlobalSearchFilter;
+  limit?: number;
+} = {}) {
+  const { currentLocale } = useLanguage();
+  const [query, setQuery] = useState(initialQuery);
+  const [filter, setFilter] = useState<GlobalSearchFilter>(initialFilter);
+  const [results, setResults] = useState<GlobalSearchResult[]>([]);
+  const [counts, setCounts] = useState<GlobalSearchResponse['counts']>({
+    all: 0,
+    page: 0,
+    post: 0,
+    product: 0,
+  });
+  const [status, setStatus] = useState<SearchStatus>('idle');
+
+  const normalizedQuery = useMemo(() => query.replace(/\s+/g, ' ').trim(), [query]);
+  const canSearch = normalizedQuery.length >= 2;
+
+  useEffect(() => {
+    if (!canSearch) {
+      setResults([]);
+      setCounts({ all: 0, page: 0, post: 0, product: 0 });
+      setStatus('idle');
+      return;
+    }
+
+    const controller = new AbortController();
+    const timeoutId = window.setTimeout(async () => {
+      setStatus('loading');
+
+      const params = new URLSearchParams({
+        q: normalizedQuery,
+        type: filter,
+        limit: String(limit),
+      });
+
+      if (currentLocale) {
+        params.set('locale', currentLocale);
+      }
+
+      try {
+        const response = await fetch(`/api/search?${params.toString()}`, {
+          signal: controller.signal,
+        });
+
+        if (!response.ok) {
+          throw new Error(`Search request failed with ${response.status}`);
+        }
+
+        const payload = (await response.json()) as GlobalSearchResponse;
+        setResults(payload.results);
+        setCounts(payload.counts);
+        setStatus('success');
+      } catch (error) {
+        if ((error as Error).name === 'AbortError') {
+          return;
+        }
+
+        console.error('Global search request failed:', error);
+        setResults([]);
+        setCounts({ all: 0, page: 0, post: 0, product: 0 });
+        setStatus('error');
+      }
+    }, 180);
+
+    return () => {
+      controller.abort();
+      window.clearTimeout(timeoutId);
+    };
+  }, [canSearch, currentLocale, filter, limit, normalizedQuery]);
+
+  return {
+    query,
+    setQuery,
+    filter,
+    setFilter,
+    results,
+    counts,
+    status,
+    canSearch,
+    isLoading: status === 'loading',
+  };
+}

package/templates/nextblock-template/index.d.ts

@@ -1,7 +1,7 @@
-declare module '*.svg' {
-  const content: any;
-  export const ReactComponent: any;
-  export default content;
-}
-
-declare module 'uuid';
+declare module '*.svg' {
+  const content: any;
+  export const ReactComponent: any;
+  export default content;
+}
+
+declare module 'uuid';