Compare commits

...

37 Commits

Author SHA1 Message Date
Peter White 825bdc6a2c changeset 2026-11-18 23:29:58 +00:00
Peter White e4687a9177 Emit an escape event from the Docs Embed 2026-11-18 23:29:58 +00:00
Peter White 7ad3fff118 Open links in the tab their author chose (#4802) 2026-11-18 15:24:51 +01:00
Peter White 386a5c18eb Simplify search results and let hover select a result (#4806) 2026-11-18 15:12:09 +01:00
conico974 a3b5ce5b7e Render the llms.txt directive as the first element in <body> (#4801)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 13:19:09 +01:00
Nolann B. 818cbbeb38 Answer Assistant questions with medium reasoning (#4700) 2026-11-18 13:01:20 +01:00
Peter White 629916b96f Track GBO production releases in Linear (#4803) 2026-11-18 11:43:35 +01:00
Peter White be6e324327 Keep held-search tests on the search route when the site gives a search pass (#4804) 2026-11-18 11:20:29 +01:00
Peter White ae1e370c48 Stop the table of contents layout loop in older Chrome (#4800) 2026-11-18 09:03:01 +01:00
Peter White adbec4c832 Send each search once on sites without a top header (#4781) 2026-11-17 12:10:19 +00:00
Peter White 8f5175e69e Show result-shaped placeholders while search loads (#4779) 2026-11-17 12:10:19 +00:00
Peter White 7856e08c15 Show one server-ordered search list and open its top result on Enter (#4777) 2026-11-17 12:10:18 +00:00
Peter White e0b512e689 Ask for a comms decision before default-on live site changes (#4799) 2026-11-17 12:00:41 +00:00
Peter White 6cdbafcda6 [RND-8403] Respect a site's setting to turn off change request previews (#4797) 2026-11-17 11:12:01 +00:00
Peter White d55e8f90c2 Make the no-pass search test independent of the search pass flag (#4798) 2026-11-17 11:56:32 +01:00
Brett Jephson 960d7ec6e2 Fade collapsed code blocks on published sites (#4793)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 10:37:22 +00:00
Peter White cf8c3d52f3 Search the API directly from the browser with a search pass (#4784) 2026-11-17 10:35:54 +01:00
Peter White 4eb32b1534 Use absolute links in generated Markdown (#4795) 2026-11-17 10:11:23 +01:00
Peter White b5f7e55818 Render Small cards in published sites (#4796) 2026-11-17 09:34:22 +01:00
Nolann B. 262749a0b1 Copy the current spec's server in OpenAPI endpoint URLs (#4794) 2026-11-16 20:12:40 +01:00
Peter White b145bfcdff Stop caching site search results (#4782) 2026-11-16 16:43:30 +01:00
Peter White 1c718491bd Follow the API's cache lifetime for site data (#4790) 2026-11-16 14:10:44 +01:00
Viktor Renkema 8dd308bd90 Ignore categories when resolving tag assignments (#4736) 2026-11-16 10:49:18 +01:00
Peter White c09da2ec1a Show H3 headings in the page outline (#4787) 2026-11-16 10:47:57 +01:00
conico974 9fcde5f487 Reduce memory and CPU use of the OpenNext workers (#4788)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 10:17:23 +01:00
conico974 c85d84fc1d Store 'use cache' entries in R2 again (#4789)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 10:15:41 +01:00
Peter White c3df458378 Keep inline code readable over a background page cover (#4778) 2026-11-13 13:28:17 +01:00
conico974 ddccd3d4f0 Bump Next.js to 16.4.6 and OpenNext to 1.20.17 (#4776)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 13:28:03 +01:00
Peter White adfd921b3a Search one language in the MCP search tool (#4775) 2026-11-13 10:37:44 +01:00
Nolann B. 5997a66638 Remove duplicated declarations from the global stylesheet (#4764)
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-12 18:23:37 +01:00
Nolann B. 65210b7d1d Respect reduced motion and forced colors, use dynamic viewport units (#4763)
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-12 18:23:37 +01:00
Nolann B. 265ca4bd9d Improve keyboard and screen reader support (#4761)
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-12 18:23:36 +01:00
Nolann B. 3e86382cdc Tighten the referrer policy and the embed channel handshake (#4759)
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-12 18:23:36 +01:00
Nolann B. 19660edf91 Fix quick accessibility and input bugs, tune network priorities (#4758)
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-12 18:23:35 +01:00
Nolann B. e3d22380fc Improve preview deployment workflow reliability (#4772)
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-12 16:58:21 +00:00
Nolann B. 9b5b8c85ec Load the OpenAPI stylesheet only on pages with OpenAPI blocks (#4770) 2026-11-12 16:21:51 +01:00
Nolann B. 0c3a51eca4 Stop card carousels from widening the page (#4768)
Co-authored-by: Claude <noreply@anthropic.com>
2026-11-12 15:31:58 +01:00
208 changed files with 4684 additions and 2364 deletions
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Keep links in generated Markdown usable outside the source page.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Fade the bottom of collapsed code blocks so readers can tell there is more code, matching the editor.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Answer Assistant questions with medium reasoning instead of low, matching AI search.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Bump Next.js to 16.4.6 and OpenNext (Cloudflare 1.20.17, AWS 4.1.16), keeping the dev-mode OOM patch.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Fix horizontal page scroll caused by card carousels bleeding past the viewport.
+6
View File
@@ -0,0 +1,6 @@
---
"@gitbook/embed": minor
"gitbook": patch
---
Emit an `escape` event from the Docs Embed when Escape is pressed inside it and nothing in the embed used it, so the host can close its own panel.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Fix the table of contents keeping published pages busy in older Chrome versions such as Chrome 130.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Fix `'use cache'` entries never being stored in or read from R2 and the regional cache on Cloudflare.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Remove duplicated declarations from the global stylesheet.
@@ -0,0 +1,5 @@
---
"@gitbook/icons": minor
---
Add a `@gitbook/icons/validateIconName` entry that validates icon names without loading the icon labels and search terms.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Keep inline code and highlighted text readable when a paragraph crosses the bottom edge of a background page cover.
@@ -0,0 +1,6 @@
---
"gitbook": patch
"@gitbook/icons": patch
---
Add a skip link, keyboard navigation between content tabs, focusable table of contents toggles, and hide decorative icons from assistive technologies.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Reduce memory and CPU use of the OpenNext workers: minify the middleware, resolve the site context once per request, cache parsed OpenAPI descriptions across a spec, drop the redis client and the unused force-revalidate route from the server bundle.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Load the OpenAPI stylesheet only on pages with OpenAPI blocks.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Render the llms.txt directive as the first element in the page body so agents find it before the navigation.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Limit the MCP `searchDocumentation` tool to one language: the one the client passes in the new optional `language` argument, or else the language of the site variant the MCP endpoint is served from.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Flush insights events when the page is hidden, preload the search index at low priority and prioritize the dark page cover on dark-default sites.
@@ -0,0 +1,5 @@
---
"@gitbook/react-openapi": patch
---
Copy the current spec's server in OpenAPI endpoint URLs instead of a server kept from a previously visited page.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Show H3 headings in the page outline.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": minor
---
Open a link in the same or a new tab when its author chose one, instead of the site-wide external links setting.
+5
View File
@@ -0,0 +1,5 @@
---
'gitbook': patch
---
Respect disabled change request previews on published sites.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Fix the search button accessible name, hoverable link previews, IME-safe Enter on Safari, cookie banner semantics, active outline item announcement and textarea shrinking.
@@ -0,0 +1,6 @@
---
"gitbook": patch
"@gitbook/embed": patch
---
Respect reduced motion for enter and exit animations, keep the header separator and input focus visible in forced colors mode, and size mobile surfaces with dynamic viewport units.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Send only the site origin as referrer to third parties, and only let the embedding page open the embed messaging channel.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Send site searches straight to the search API when the site hands out a search pass, and use the site's search route when it does not or when the API refuses a search.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Send each search once on sites without a top header, and make search work between 768 and 1023 px wide.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Show loading rows shaped like search results while search waits for the server.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Show search results with one-line breadcrumbs and no icons or shortcut hints, and select the result under the mouse.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Stop caching site search results in the framework cache, so every search reaches the API.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Show one server-ordered search list and open its top result on Enter.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Follow the API's cache lifetime for site data, so a site preview shows layout changes soon after they are saved.
+5
View File
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Render small cards in a responsive four-column grid and carousel.
@@ -0,0 +1,5 @@
---
"gitbook": patch
---
Ignore tag category references when displaying assigned tags and update filters.
+42 -16
View File
@@ -4,6 +4,11 @@ on:
push:
branches:
- main
# A newer run for the same PR supersedes the previous one. Each push to main gets a group of its
# own, so main runs are never queued behind or cancelled by another run.
concurrency:
group: ${{ github.event_name == 'pull_request_target' && format('preview-pr-{0}', github.event.pull_request.number) || format('preview-run-{0}', github.run_id) }}
cancel-in-progress: ${{ github.event_name == 'pull_request_target' }}
jobs:
approval:
# Ensure that external contributors' PRs are manually approved before deployment
@@ -18,8 +23,9 @@ jobs:
deploy-v2-vercel:
name: Deploy v2 to Vercel (preview)
runs-on: ubuntu-latest
timeout-minutes: 20
needs: approval
if: ${{ always() && (needs.approval.result == 'success' || needs.approval.result == 'skipped') }}
if: ${{ !cancelled() && (needs.approval.result == 'success' || needs.approval.result == 'skipped') }}
environment:
name: 2v-preview
url: ${{ steps.deploy.outputs.deployment-url }}
@@ -44,8 +50,9 @@ jobs:
deploy-v2-cloudflare:
name: Deploy v2 to Cloudflare Worker (preview)
runs-on: ubuntu-latest
timeout-minutes: 20
needs: approval
if: ${{ always() && (needs.approval.result == 'success' || needs.approval.result == 'skipped') }}
if: ${{ !cancelled() && (needs.approval.result == 'success' || needs.approval.result == 'skipped') }}
environment:
name: 2c-preview
url: ${{ steps.deploy.outputs.deployment-url }}
@@ -82,7 +89,7 @@ jobs:
comment-deployments:
runs-on: ubuntu-latest
name: Comment Deployments (preview)
if: always() && github.event_name != 'push'
if: ${{ !cancelled() && github.event_name != 'push' }}
needs:
- deploy-v2-vercel
- deploy-v2-cloudflare
@@ -95,6 +102,25 @@ jobs:
comment-author: 'github-actions[bot]'
body-includes: 'Summary of the deployments'
# A deploy that didn't succeed has no URL (e.g. a re-run hitting Vercel's "deploymentId
# already exists"), so keep the URL the comment already shows instead of blanking it.
- name: Resolve deployment URLs
id: urls
env:
PREVIOUS_COMMENT: ${{ steps.fc.outputs.comment-body }}
VERCEL_RESULT: ${{ needs.deploy-v2-vercel.result }}
VERCEL_URL: ${{ needs.deploy-v2-vercel.outputs.deployment-url }}
CLOUDFLARE_RESULT: ${{ needs.deploy-v2-cloudflare.result }}
CLOUDFLARE_URL: ${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}
run: |
previous_url() {
sed -n "s/^| $1 | \[\([^]]*\)\].*/\1/p" <<<"$PREVIOUS_COMMENT" | head -n 1
}
if [ "$VERCEL_RESULT" != success ]; then VERCEL_URL=$(previous_url Vercel); fi
if [ "$CLOUDFLARE_RESULT" != success ]; then CLOUDFLARE_URL=$(previous_url Cloudflare); fi
echo "vercel=$VERCEL_URL" >> "$GITHUB_OUTPUT"
echo "cloudflare=$CLOUDFLARE_URL" >> "$GITHUB_OUTPUT"
- name: Create or update GitHub comment
uses: peter-evans/create-or-update-comment@v4
with:
@@ -105,21 +131,21 @@ jobs:
| Version | URL | Status |
| --- | --- | --- |
| Vercel | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}](${{ needs.deploy-v2-vercel.outputs.deployment-url }}) | ${{ needs.deploy-v2-vercel.result == 'success' && '✅' || '❌' }} |
| Cloudflare | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}) | ${{ needs.deploy-v2-cloudflare.result == 'success' && '✅' || '❌' }} |
| Vercel | [${{ steps.urls.outputs.vercel }}](${{ steps.urls.outputs.vercel }}) | ${{ needs.deploy-v2-vercel.result == 'success' && '✅' || '❌' }} |
| Cloudflare | [${{ steps.urls.outputs.cloudflare }}](${{ steps.urls.outputs.cloudflare }}) | ${{ needs.deploy-v2-cloudflare.result == 'success' && '✅' || '❌' }} |
### Test content
| Site | `2v` | `2c` |
| --- | --- | --- |
| GitBook | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.com/docs](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.com/docs) | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.com/docs](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.com/docs) |
| E2E | [${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-vercel.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) | [${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open](${{ needs.deploy-v2-cloudflare.outputs.deployment-url }}/url/gitbook.gitbook.io/test-gitbook-open) |
| GitBook | [${{ steps.urls.outputs.vercel }}/url/gitbook.com/docs](${{ steps.urls.outputs.vercel }}/url/gitbook.com/docs) | [${{ steps.urls.outputs.cloudflare }}/url/gitbook.com/docs](${{ steps.urls.outputs.cloudflare }}/url/gitbook.com/docs) |
| E2E | [${{ steps.urls.outputs.vercel }}/url/gitbook.gitbook.io/test-gitbook-open](${{ steps.urls.outputs.vercel }}/url/gitbook.gitbook.io/test-gitbook-open) | [${{ steps.urls.outputs.cloudflare }}/url/gitbook.gitbook.io/test-gitbook-open](${{ steps.urls.outputs.cloudflare }}/url/gitbook.gitbook.io/test-gitbook-open) |
edit-mode: replace
visual-testing-v2-vercel:
runs-on: ubuntu-latest
name: Visual Testing v2
needs: deploy-v2-vercel
if: ${{ always() && needs.deploy-v2-vercel.result == 'success' }}
if: ${{ !cancelled() && needs.deploy-v2-vercel.result == 'success' }}
timeout-minutes: 15
steps:
- name: Checkout
@@ -143,7 +169,7 @@ jobs:
runs-on: ubuntu-latest
name: Visual Testing v2 (Cloudflare)
needs: deploy-v2-cloudflare
if: ${{ always() && needs.deploy-v2-cloudflare.result == 'success' }}
if: ${{ !cancelled() && needs.deploy-v2-cloudflare.result == 'success' }}
timeout-minutes: 15
steps:
- name: Checkout
@@ -167,7 +193,7 @@ jobs:
runs-on: ubuntu-latest
name: Visual Testing Customers v2
needs: deploy-v2-vercel
if: ${{ always() && needs.deploy-v2-vercel.result == 'success' }}
if: ${{ !cancelled() && needs.deploy-v2-vercel.result == 'success' }}
timeout-minutes: 30
steps:
- name: Checkout
@@ -191,7 +217,7 @@ jobs:
# Style recalc depends on the client bundle, not the host, so this runs here only and
# not in the Cloudflare job. Kept out of `e2e-customers`, which is a visual suite.
- name: Run style invalidation tests
if: always()
if: ${{ !cancelled() }}
working-directory: packages/gitbook
run: bun run e2e-style-perf
env:
@@ -200,7 +226,7 @@ jobs:
# Runs on failure too: a blown style budget is exactly when the numbers are worth seeing.
- name: Build style invalidation report
if: always() && github.event_name != 'push'
if: ${{ !cancelled() && github.event_name != 'push' }}
id: style-perf
working-directory: packages/gitbook
run: |
@@ -219,7 +245,7 @@ jobs:
} >> "$GITHUB_OUTPUT"
- name: Find style invalidation comment
if: always() && github.event_name != 'push' && steps.style-perf.outputs.body != ''
if: ${{ !cancelled() && github.event_name != 'push' && steps.style-perf.outputs.body != '' }}
uses: peter-evans/find-comment@v3
id: fc-style-perf
with:
@@ -228,7 +254,7 @@ jobs:
body-includes: 'Style invalidation on a large API reference'
- name: Create or update style invalidation comment
if: always() && github.event_name != 'push' && steps.style-perf.outputs.body != ''
if: ${{ !cancelled() && github.event_name != 'push' && steps.style-perf.outputs.body != '' }}
uses: peter-evans/create-or-update-comment@v4
with:
comment-id: ${{ steps.fc-style-perf.outputs.comment-id }}
@@ -239,7 +265,7 @@ jobs:
runs-on: ubuntu-latest
name: Visual Testing Customers v2 (Cloudflare)
needs: deploy-v2-cloudflare
if: ${{ always() && needs.deploy-v2-cloudflare.result == 'success' }}
if: ${{ !cancelled() && needs.deploy-v2-cloudflare.result == 'success' }}
timeout-minutes: 30
steps:
- name: Checkout
@@ -263,7 +289,7 @@ jobs:
runs-on: ubuntu-latest
name: Browserless Testing v2 (Vercel)
needs: deploy-v2-vercel
if: ${{ always() && needs.deploy-v2-vercel.result == 'success' }}
if: ${{ !cancelled() && needs.deploy-v2-vercel.result == 'success' }}
steps:
- name: Checkout
uses: actions/checkout@v4
+28
View File
@@ -51,3 +51,31 @@ jobs:
- name: Outputs
run: |
echo "URL: ${{ steps.deploy.outputs.deployment-url }}"
linear-release:
name: Track the production release in Linear
needs: [deploy-v2-vercel, deploy-v2-cloudflare]
runs-on: ubuntu-latest
timeout-minutes: 10
# Release tracking must never fail a deployment that already succeeded.
continue-on-error: true
permissions:
contents: read
env:
LINEAR_ACCESS_KEY: ${{ secrets.PRODUCTION_LINEAR_RELEASE_ACCESS_KEY }}
steps:
- name: Skip release tracking without an access key
if: env.LINEAR_ACCESS_KEY == ''
run: echo "::warning::No Linear pipeline access key is configured, skipped tracking the release."
- name: Checkout
if: env.LINEAR_ACCESS_KEY != ''
uses: actions/checkout@v4
with:
# The Linear CLI scans commit metadata since the last release, so it needs history but no blobs.
fetch-depth: 0
filter: blob:none
persist-credentials: false
- name: Sync the release to Linear
if: env.LINEAR_ACCESS_KEY != ''
uses: linear/linear-release-action@dd4fc407f860b9460d2cf0b3fb1edd8985cf443f # v0.18.2
with:
access_key: ${{ env.LINEAR_ACCESS_KEY }}
+30
View File
@@ -59,6 +59,36 @@ Run a specific test file:
cd packages/gitbook && bun test src/lib/cache.test.ts
```
## Changes customers see on their live site
Published sites are our customers' product. If a change alters how their content looks or behaves without them changing anything, it needs a comms decision before it merges.
It counts if it ships on by default and any of these are true:
- It changes structure or navigation: outline/"On this page", sidebar, TOC, headings, breadcrumbs, pagination, header or footer.
- Something new appears on every page (or every page of a type), or something existing disappears or moves.
- Layout or typography shifts enough that a customer would notice in a screenshot.
- URLs, anchors, redirects, SEO/meta tags or search/Ask behaviour change.
- A default changes for existing sites.
It does not count when:
- It's behind a flag, a site setting or opt-in that stays off for existing sites until comms go out.
- It's a bug fix that restores the intended behaviour.
- It only affects the editor/app, not published content.
When it counts:
1. Warn the engineer before the PR is opened: "This changes customers' live sites. Have the support and sales leads agreed the rollout and announcement?"
2. Suggest a flag or staged rollout if there isn't one, so it can ship dark and be turned on after the notice goes out.
## Bumping Next.js or OpenNext
Type checks and unit tests miss runtime regressions: OpenNext 4.1.15 changed the composable cache key format, and every `'use cache'` call silently missed for days. Before committing a bump of `next`, `@opennextjs/aws` or `@opennextjs/cloudflare`, run both runtimes locally from `packages/gitbook`:
1. **Next**: `bun run build:local && bun run start`, then load several distinct pages under `http://localhost:3000/url/gitbook.com/docs`.
2. **OpenNext**: `bun run build:cloudflare`, delete `openNext/customWorkers/.wrangler` (stale cache hits otherwise skip the server), then run `bun run dev:cf:server` and `bun run dev:cf:middleware` and load several distinct pages under `http://127.0.0.1:8771/url/gitbook.com/docs`.
3. Diff the changed OpenNext versions' adapters that call our overrides in `openNext/` (incremental, composable and tag cache, queue), e.g. with `npm pack` of the old and new versions.
The bump is safe when every page returns 200 on both runtimes and the server logs show no cache errors (grep `Failed to` and `regional cache`). Report the pages checked and the log result in the PR.
## Changesets
After committing code changes, create a changeset for the affected package:
+30 -47
View File
@@ -8,7 +8,7 @@
"@changesets/cli": "^2.31.1",
"oxfmt": "^0.62.0",
"oxlint": "^1.93.0",
"turbo": "^2.11.10",
"turbo": "^2.11.11",
"vercel": "50.37.3",
},
},
@@ -128,8 +128,8 @@
"@gitbook/react-openapi": "workspace:*",
"@mermaid-js/mermaid-zenuml": "^0.2.2",
"@modelcontextprotocol/sdk": "1.17.5",
"@opennextjs/aws": "4.1.15",
"@opennextjs/cloudflare": "1.20.16",
"@opennextjs/aws": "4.1.16",
"@opennextjs/cloudflare": "1.20.17",
"@panzoom/panzoom": "^4.6.1",
"@sindresorhus/fnv1a": "^3.1.0",
"@tailwindcss/container-queries": "^0.1.1",
@@ -159,7 +159,7 @@
"micromark-extension-gfm": "^3.0.0",
"motion": "^12.23.24",
"negotiator": "^1.0.0",
"next": "^16.4.5",
"next": "^16.4.6",
"next-themes": "^0.4.6",
"nuqs": "^2.2.3",
"object-hash": "^3.0.0",
@@ -167,6 +167,7 @@
"openapi-types": "^12.1.3",
"p-map": "^7.0.3",
"p-retry": "^8.0.0",
"parse5": "7.2.0",
"quick-lru": "^7.0.1",
"react": "19.2.4",
"react-dom": "19.2.4",
@@ -341,9 +342,9 @@
},
"patchedDependencies": {
"decode-named-character-reference@1.0.2": "patches/decode-named-character-reference@1.0.2.patch",
"next@16.4.5": "patches/next@16.4.5.patch",
"@shikijs/langs@3.21.0": "patches/@shikijs%2Flangs@3.21.0.patch",
"mermaid@11.16.1": "patches/mermaid@11.16.1.patch",
"next@16.4.6": "patches/next@16.4.6.patch",
},
"overrides": {
"@codemirror/state": "6.4.1",
@@ -356,7 +357,7 @@
},
"catalog": {
"@base-ui/react": "^1.7.0",
"@gitbook/api": "0.208.0",
"@gitbook/api": "0.210.0",
"@scalar/api-client-react": "^1.3.46",
"@tsconfig/node20": "^20.1.6",
"@tsconfig/strictest": "^2.0.6",
@@ -724,7 +725,7 @@
"@fortawesome/fontawesome-svg-core": ["@fortawesome/fontawesome-svg-core@7.2.0", "", { "dependencies": { "@fortawesome/fontawesome-common-types": "7.2.0" } }, "sha512-6639htZMjEkwskf3J+e6/iar+4cTNM9qhoWuRfj9F3eJD6r7iCzV1SWnQr2Mdv0QT0suuqU8BoJCZUyCtP9R4Q=="],
"@gitbook/api": ["@gitbook/api@0.208.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-i5rnGYNvgp8PDGd9FRLUjOx5gS/D7mFfikwp0Lsem4pgEG8cqBtZsDaYbLBdAdupOuZBLJtmEut51zhttok6OQ=="],
"@gitbook/api": ["@gitbook/api@0.210.0", "", { "dependencies": { "event-iterator": "^2.0.0", "eventsource-parser": "^3.0.0" } }, "sha512-qxroJUFDreoJNU7X28Gz+2Nbjg8PCiE4GtJkwscHYfmWHLM29NsVVt3ap8x+bz53j6mg+SaobVjeRsXdA1EbXA=="],
"@gitbook/browser-types": ["@gitbook/browser-types@workspace:packages/browser-types"],
@@ -888,29 +889,29 @@
"@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.0.6", "", { "dependencies": { "@emnapi/core": "^1.5.0", "@emnapi/runtime": "^1.5.0", "@tybys/wasm-util": "^0.10.1" } }, "sha512-DXj75ewm11LIWUk198QSKUTxjyRjsBwk09MuMk5DGK+GDUtyPhhEHOGP/Xwwj3DjQXXkivoBirmOnKrLfc0+9g=="],
"@next/env": ["@next/env@16.4.5", "", {}, "sha512-JwSPwpdkZL5VMl2jA/q+JI8MZdweAL3xmw5/tb9y/TLtmS0YXZnmYDzSihwk8xTj1OL+WM53gTqaj96yuLp6Xw=="],
"@next/env": ["@next/env@16.4.6", "", {}, "sha512-SunBjJ6t+oBtecS3dTjdVuMhUogP5wD/vrGL5EVuQYM1iS4O5ilL51HkiJ3sPjMzRHiCChvr4dbaSJbR7F3lxA=="],
"@next/swc-darwin-arm64": ["@next/swc-darwin-arm64@16.4.5", "", { "os": "darwin", "cpu": "arm64" }, "sha512-W5TniBzWKASbNNwHZ/S/f1MxQUXU/LdjklVMWA0Ujbfl7SZnUzFls45hO0i/sF7Bx1jJBWp7WWmoQajXtX/O8A=="],
"@next/swc-darwin-arm64": ["@next/swc-darwin-arm64@16.4.6", "", { "os": "darwin", "cpu": "arm64" }, "sha512-kJ4VVZkley17xKaJx72QN2IBqjrj7zenCQZaUF0l9ShS/1Mt2kW4+Z5KGG6vgr3L/J562xTOizVyM1iA/u5nlg=="],
"@next/swc-darwin-x64": ["@next/swc-darwin-x64@16.4.5", "", { "os": "darwin", "cpu": "x64" }, "sha512-uWq4qkHapBDS1oFltWS4YxTb9pLHAtLNcpbuK6SmRsebLYZqpBML/j/C0op+50JYGTpZgVL/DWNt/6oWlamrrw=="],
"@next/swc-darwin-x64": ["@next/swc-darwin-x64@16.4.6", "", { "os": "darwin", "cpu": "x64" }, "sha512-eIPGZIqC+8JKaeZmvnCANJQF4xWkkHqSnAAajtFxgwDMAOnCgxNvP52SeWZ41PyVwoe+Le/NQuZSaQ8j7YshSA=="],
"@next/swc-linux-arm64-gnu": ["@next/swc-linux-arm64-gnu@16.4.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-FdRcyOx5u5P51mlAqLB9EXdd8jZO5fsdHtk4BAQSkqOywCsbTNN/rmw+jO7pnmjNdAtu2AG46NzbCL2FPDrrgw=="],
"@next/swc-linux-arm64-gnu": ["@next/swc-linux-arm64-gnu@16.4.6", "", { "os": "linux", "cpu": "arm64" }, "sha512-9nI6O8vvczH2D9ZNdMGqb/3NuT15T9ksOZnAmx9/gjF2cOi74+xxyf1Hk96uIMfm14c9y6wHeBq6SH8g6udvcA=="],
"@next/swc-linux-arm64-musl": ["@next/swc-linux-arm64-musl@16.4.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-cyvmmgtRXR8aGVT86wi9Py53IlfyCx7P2fZxuAXAoTummDnhKtUyjrMeXfapqp4qgD+gT5RqyGD/VfA16jEK7Q=="],
"@next/swc-linux-arm64-musl": ["@next/swc-linux-arm64-musl@16.4.6", "", { "os": "linux", "cpu": "arm64" }, "sha512-7/qPhTxDp2ScluOJOhLuhWmlA17o1yZ0SIgpISBCpBxXgtnK4+KGywBpFkfLPiU1rnSM1faFGzYkH6i7JdTrqA=="],
"@next/swc-linux-x64-gnu": ["@next/swc-linux-x64-gnu@16.4.5", "", { "os": "linux", "cpu": "x64" }, "sha512-hPc+Fl+N22DAvqZHq559NmamXboOX5Lu8I5Wl0DezfrhTk1Zz21NQeYoZDmNI/NjTcrdsVxM72Fzn2lI+Q+vAw=="],
"@next/swc-linux-x64-gnu": ["@next/swc-linux-x64-gnu@16.4.6", "", { "os": "linux", "cpu": "x64" }, "sha512-oOpbNa8XOW1qCGd9VvzC4fbkkRxEls7/WI6tz+YHC0xRA7KpV1U7DrAnCPjzVyOk/karzWEepCOcTIDmwK8FwQ=="],
"@next/swc-linux-x64-musl": ["@next/swc-linux-x64-musl@16.4.5", "", { "os": "linux", "cpu": "x64" }, "sha512-gbACYE8IP/jlprNTpiWXHb8N9CofOzpnEwH2SrIz1dUbiJf1FbDssDupCAPeP1Taxe8mgG20sGZamJI7KFOdZw=="],
"@next/swc-linux-x64-musl": ["@next/swc-linux-x64-musl@16.4.6", "", { "os": "linux", "cpu": "x64" }, "sha512-aM8CZ+OR2EwXaAYw7KGkW2GDmNDsLBIRe1MMRZCJPTdw/xhTD0IMUVO4sf3KqrzuRouGzwwLZn34+gFeVXiUQA=="],
"@next/swc-win32-arm64-msvc": ["@next/swc-win32-arm64-msvc@16.4.5", "", { "os": "win32", "cpu": "arm64" }, "sha512-+8gj++ZMo8H20Xh2ijjNqyFk5LPLw0AC4Fs4Tq/G94rjjQXhOjN4jgSWsWKPFsyY26hfIeemJIwKtMxOsp5GBA=="],
"@next/swc-win32-arm64-msvc": ["@next/swc-win32-arm64-msvc@16.4.6", "", { "os": "win32", "cpu": "arm64" }, "sha512-U0p7/tEtqvHX2crhd841CDwKtp5CFkKXVjOhmfccR3Pvp64sj8KBwRqsvltqLOwVBbj0NtkxwXSDpEHYGbxeXQ=="],
"@next/swc-win32-x64-msvc": ["@next/swc-win32-x64-msvc@16.4.5", "", { "os": "win32", "cpu": "x64" }, "sha512-qNZj66pYXnaWLiF9R9GUbfBdrCv7kC6TaZfIwB2KH5WPc/8pEM3nVOj8hpQhWJU8S94rlH5MPDcX15+RrgUhiw=="],
"@next/swc-win32-x64-msvc": ["@next/swc-win32-x64-msvc@16.4.6", "", { "os": "win32", "cpu": "x64" }, "sha512-3ZG15/5WIdlTQsIEvc9sPTTSL5XFrlLklIKmfF4fwsDnoAhu6NcBDXsk3mbGxNyo6aVLEGex+fHCv2MahY7a9g=="],
"@node-minify/core": ["@node-minify/core@9.0.2", "", { "dependencies": { "@node-minify/utils": "9.0.1", "glob": "10.3.3", "mkdirp": "3.0.1" } }, "sha512-FNhv29Wom6wKrrFKaeAfmZqz7TX5A1E6P+bpd0VIc+DYWMLUIhAViS8riaZg3A1oD0s06s+5BG2Fg7RqMKiKHw=="],
"@node-minify/core": ["@node-minify/core@10.5.0", "", { "dependencies": { "@node-minify/utils": "10.5.0" } }, "sha512-duptyliRQY+fXszqbm5CP+NauASUwkOlx/c4bwlT7tj5AQWhG9F26D3bfU/okKto9RDTGJy3cLwPvJC/j9lCkA=="],
"@node-minify/terser": ["@node-minify/terser@9.0.1", "", { "dependencies": { "@node-minify/utils": "9.0.1", "terser": "5.36.0" } }, "sha512-WF78Ex+/xNZZDYvzwB7+sLUYQbJzyyS36ZjMhVqhORejHOsoOcTjQ9TdOgKZoY7wlfxjnLxeMKkO8R/R1KL9aQ=="],
"@node-minify/terser": ["@node-minify/terser@10.5.0", "", { "dependencies": { "@node-minify/utils": "10.5.0", "terser": "5.46.0" } }, "sha512-NvR9vYMQ/exd2lNKQ9TtoJD98gqpzQu0+bIZRqA3mci38hmacPr7H5cP4coh1vz5ZZp+WkYSrOwCm2FiC2P5MQ=="],
"@node-minify/utils": ["@node-minify/utils@9.0.1", "", { "dependencies": { "gzip-size": "6.0.0" } }, "sha512-aC1+mhKTP3IMa2VcuGl3ui92LO/7CPQWldNGzu3BVGKiMNJ70AKJW/R6huuYCSuQyHDGM9oFwiVClsZnFxn67g=="],
"@node-minify/utils": ["@node-minify/utils@10.5.0", "", { "dependencies": { "fast-glob": "^3.3.3", "gzip-size": "7.0.0" } }, "sha512-3DZEYgersSgia5V/cee35sw6B7TTZlcCKyAGiuhT274/r1obMEtHt1lRmyCd52uX5QlZqDOTrD4bqHCxKzIYLg=="],
"@nodelib/fs.scandir": ["@nodelib/fs.scandir@2.1.5", "", { "dependencies": { "@nodelib/fs.stat": "2.0.5", "run-parallel": "^1.1.9" } }, "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g=="],
@@ -934,9 +935,9 @@
"@octokit/types": ["@octokit/types@14.1.0", "", { "dependencies": { "@octokit/openapi-types": "^25.1.0" } }, "sha512-1y6DgTy8Jomcpu33N+p5w58l6xyt55Ar2I91RPiIA0xCJBXyUAhXCcmZaDWSANiha7R9a6qJJ2CRomGPZ6f46g=="],
"@opennextjs/aws": ["@opennextjs/aws@4.1.15", "", { "dependencies": { "@ast-grep/napi": "^0.45.3", "@aws-sdk/client-cloudfront": "3.984.0", "@aws-sdk/client-dynamodb": "3.984.0", "@aws-sdk/client-lambda": "3.984.0", "@aws-sdk/client-s3": "3.984.0", "@aws-sdk/client-sqs": "3.984.0", "@node-minify/core": "^9.0.2", "@node-minify/terser": "^9.0.1", "@tsconfig/node18": "^18.2.7", "aws4fetch": "^1.0.20", "chalk": "^5.6.2", "cookie": "^1.1.1", "esbuild": "0.28.2", "express": "^5.2.1", "path-to-regexp": "^6.3.0", "urlpattern-polyfill": "^10.1.0", "yaml": "^2.9.1" }, "peerDependencies": { "diff": "^9.0.0", "next": ">=15.5.29 <16 || >=16.4.5" }, "optionalPeers": ["diff"], "bin": { "open-next": "dist/index.js" } }, "sha512-ulv7rFEAeieD0d/zDMnw4IFPU+zY/atVUhn7ezgFqIurLB5oBYeHCUGlcGk3Pg7uMPeI03SNRjHW1+xL9EwMPw=="],
"@opennextjs/aws": ["@opennextjs/aws@4.1.16", "", { "dependencies": { "@ast-grep/napi": "^0.45.3", "@aws-sdk/client-cloudfront": "3.984.0", "@aws-sdk/client-dynamodb": "3.984.0", "@aws-sdk/client-lambda": "3.984.0", "@aws-sdk/client-s3": "3.984.0", "@aws-sdk/client-sqs": "3.984.0", "@node-minify/core": "^10.5.0", "@node-minify/terser": "^10.5.0", "@tsconfig/node18": "^18.2.7", "aws4fetch": "^1.0.20", "chalk": "^5.6.2", "cookie": "^1.1.1", "esbuild": "0.28.2", "express": "^5.2.1", "path-to-regexp": "^6.3.0", "urlpattern-polyfill": "^10.1.0", "yaml": "^2.9.1" }, "peerDependencies": { "diff": "^9.0.0", "next": ">=15.5.29 <16 || >=16.4.5" }, "optionalPeers": ["diff"], "bin": { "open-next": "dist/index.js" } }, "sha512-eHb6/LCrpr+3DmbmE+/q5GkcrbSs5IRpO/O0kcay7FK5WYDhcML0K5NhO7I9H62z42wscVIi75Hv3ASsXDeEGw=="],
"@opennextjs/cloudflare": ["@opennextjs/cloudflare@1.20.16", "", { "dependencies": { "@ast-grep/napi": "^0.45.3", "@dotenvx/dotenvx": "^2.33.0", "@opennextjs/aws": "4.1.15", "ci-info": "^4.2.0", "cloudflare": "^4.4.1", "comment-json": "^4.5.1", "enquirer": "^2.4.1", "glob": "^13.0.6", "ts-tqdm": "^0.8.6", "yargs": "^18.2.0" }, "peerDependencies": { "next": ">=15.5.29 <16 || >=16.4.5", "rclone.js": "^0.6.6", "wrangler": "^4.148.0" }, "optionalPeers": ["rclone.js"], "bin": { "opennextjs-cloudflare": "dist/cli/index.js" } }, "sha512-3c1Cwex5e2jXy4o4RZAusy8o9Uz4eowuPCjdVLYEZ/MnkAzN2jh9dOgsRjgu3wjigXuNe8rmPECmOTo+xKQHsw=="],
"@opennextjs/cloudflare": ["@opennextjs/cloudflare@1.20.17", "", { "dependencies": { "@ast-grep/napi": "^0.45.3", "@dotenvx/dotenvx": "^2.33.0", "@opennextjs/aws": "4.1.16", "ci-info": "^4.2.0", "cloudflare": "^4.4.1", "comment-json": "^4.5.1", "enquirer": "^2.4.1", "glob": "^13.0.6", "resolve.exports": "^2.0.4", "ts-tqdm": "^0.8.6", "yargs": "^18.2.0" }, "peerDependencies": { "next": ">=15.5.29 <16 || >=16.4.5", "rclone.js": "^0.6.6", "wrangler": "^4.148.0" }, "optionalPeers": ["rclone.js"], "bin": { "opennextjs-cloudflare": "dist/cli/index.js" } }, "sha512-jGEC9ue8LLHvOFXp62LjDUSSz7JpD+PQB+Y3r0lU78PtQ84wI16+EMF9TXEDkTek3g3fGWTLTI07pbZt8/gj8w=="],
"@opentelemetry/api": ["@opentelemetry/api@1.9.0", "", {}, "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg=="],
@@ -2124,7 +2125,7 @@
"focus-trap": ["focus-trap@7.6.1", "", { "dependencies": { "tabbable": "^6.2.0" } }, "sha512-nB8y4nQl8PshahLpGKZOq1sb0xrMVFSn6at7u/qOsBZTlZRzaapISGENcB6mOkoezbClZyiMwEF/dGY8AZ00rA=="],
"foreground-child": ["foreground-child@3.3.1", "", { "dependencies": { "cross-spawn": "^7.0.6", "signal-exit": "^4.0.1" } }, "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw=="],
"foreground-child": ["foreground-child@3.3.0", "", { "dependencies": { "cross-spawn": "^7.0.0", "signal-exit": "^4.0.1" } }, "sha512-Ld2g8rrAyMYFXBhEqMz8ZAHBi4J4uS1i/CxGMDnjyFWddMXLVcDp051DZfu+t7+ab7Wv6SMqpWmyFIj5UbfFvg=="],
"form-data": ["form-data@4.0.1", "", { "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", "mime-types": "^2.1.12" } }, "sha512-tzN8e4TX8+kkxGPK8D5u0FNmjPUjw3lwC9lSLxxoB/+GtsJG91CO8bSWy73APlgAZzZbXEYZJuxjkHH2w+Ezhw=="],
@@ -2190,7 +2191,7 @@
"graceful-fs": ["graceful-fs@4.2.11", "", {}, "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ=="],
"gzip-size": ["gzip-size@6.0.0", "", { "dependencies": { "duplexer": "^0.1.2" } }, "sha512-ax7ZYomf6jqPTQ4+XCpUGyXKHk5WweS+e05MBO4/y3WJ5RkmPXNKvX+bx1behVILVwr6JSQvZAku021CHPXG3Q=="],
"gzip-size": ["gzip-size@7.0.0", "", { "dependencies": { "duplexer": "^0.1.2" } }, "sha512-O1Ld7Dr+nqPnmGpdhzLmMTQ4vAsD+rHwMm1NLUmoUFFymBOMKxCCrtDxqdBRYXdeEPEi3SyoR4TizJLQrnKBNA=="],
"hachure-fill": ["hachure-fill@0.5.2", "", {}, "sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg=="],
@@ -2338,7 +2339,7 @@
"isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
"jackspeak": ["jackspeak@2.3.6", "", { "dependencies": { "@isaacs/cliui": "^8.0.2" }, "optionalDependencies": { "@pkgjs/parseargs": "^0.11.0" } }, "sha512-N3yCS/NegsOBokc8GAdM8UcmfsKiSS8cipheD/nivzr700H+nsMOxJjQnvwOcRYVuFkdH0wGUvW2WbXGmrZGbQ=="],
"jackspeak": ["jackspeak@3.4.3", "", { "dependencies": { "@isaacs/cliui": "^8.0.2" }, "optionalDependencies": { "@pkgjs/parseargs": "^0.11.0" } }, "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw=="],
"jiti": ["jiti@2.5.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-twQoecYPiVA5K/h6SxtORw/Bs3ar+mLUtoPSc7iMXzQzK8d7eJ/R09wmTwAjiamETn1cXYPGfNnu7DMoHgu12w=="],
@@ -2636,7 +2637,7 @@
"netmask": ["netmask@2.0.2", "", {}, "sha512-dBpDMdxv9Irdq66304OLfEmQ9tbNRFnFTuZiLo+bD+r332bBmMJ8GBLXklIXXgxd3+v9+KUnZaUR5PJMa75Gsg=="],
"next": ["next@16.4.5", "", { "dependencies": { "@next/env": "16.4.5", "@swc/helpers": "0.5.23", "baseline-browser-mapping": "^2.9.19", "caniuse-lite": "^1.0.30001579", "postcss": "8.5.23", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "16.4.5", "@next/swc-darwin-x64": "16.4.5", "@next/swc-linux-arm64-gnu": "16.4.5", "@next/swc-linux-arm64-musl": "16.4.5", "@next/swc-linux-x64-gnu": "16.4.5", "@next/swc-linux-x64-musl": "16.4.5", "@next/swc-win32-arm64-msvc": "16.4.5", "@next/swc-win32-x64-msvc": "16.4.5", "sharp": "^0.35.5" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.51.1", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-rmdfsWosjTUO+6R0S3KokoIk6Kj0sWDRTe86tZHdqaWH/oXq/udX3/4xb+YQi7aWbyEFoglDU54kaifLCdXbBw=="],
"next": ["next@16.4.6", "", { "dependencies": { "@next/env": "16.4.6", "@swc/helpers": "0.5.23", "baseline-browser-mapping": "^2.9.19", "caniuse-lite": "^1.0.30001579", "postcss": "8.5.23", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "16.4.6", "@next/swc-darwin-x64": "16.4.6", "@next/swc-linux-arm64-gnu": "16.4.6", "@next/swc-linux-arm64-musl": "16.4.6", "@next/swc-linux-x64-gnu": "16.4.6", "@next/swc-linux-x64-musl": "16.4.6", "@next/swc-win32-arm64-msvc": "16.4.6", "@next/swc-win32-x64-msvc": "16.4.6", "sharp": "^0.35.5" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.51.1", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-QZJiYhaZLJMo2KpkQGQIwvmd79WVsAWeYIU554a8d7zArS3si/IRy3lBNV/rtYhE70oLwdLYhPAXLPx8HwcwtA=="],
"next-themes": ["next-themes@0.4.6", "", { "peerDependencies": { "react": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc", "react-dom": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc" } }, "sha512-pZvgD5L0IEvX5/9GWyHMf3m8BKiVQwsCMHfoFosXtXBMnaS0ZnIJ9ST4b4NqLVKDEm8QBxoNNGNaBv2JNF6XNA=="],
@@ -2902,7 +2903,7 @@
"resolve-pkg-maps": ["resolve-pkg-maps@1.0.0", "", {}, "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw=="],
"resolve.exports": ["resolve.exports@2.0.3", "", {}, "sha512-OcXjMsGdhL4XnbShKpAcSqPMzQoYkYyhbEaeSko47MjRP9NfEQMhZkXL1DoFlt9LWQn4YttrdnV6X2OiyzBi+A=="],
"resolve.exports": ["resolve.exports@2.0.4", "", {}, "sha512-zepuGL0ulf+nt+XaFrlKeaiTJeyPFPLLY62+ncq1/VTHBdt3HsfXOH60priZ6tnXQozdGcDeIF5JVTanvIcYWQ=="],
"retry": ["retry@0.13.1", "", {}, "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg=="],
@@ -3072,7 +3073,7 @@
"term-size": ["term-size@2.2.1", "", {}, "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg=="],
"terser": ["terser@5.36.0", "", { "dependencies": { "@jridgewell/source-map": "^0.3.3", "acorn": "^8.8.2", "commander": "^2.20.0", "source-map-support": "~0.5.20" }, "bin": { "terser": "bin/terser" } }, "sha512-IYV9eNMuFAV4THUspIRXkLakHnV6XO7FEdtKjf/mDyrnqUg9LnlOn6/RwRvM9SZjR4GUq8Nk8zj67FzVARr74w=="],
"terser": ["terser@5.46.0", "", { "dependencies": { "@jridgewell/source-map": "^0.3.3", "acorn": "^8.15.0", "commander": "^2.20.0", "source-map-support": "~0.5.20" }, "bin": { "terser": "bin/terser" } }, "sha512-jTwoImyr/QbOWFFso3YoU3ik0jBBDJ6JTOQiy/J2YxVJdZCc+5u7skhNwiOR3FQIygFqVUPHl7qbbxtjW2K3Qg=="],
"thenify": ["thenify@3.3.1", "", { "dependencies": { "any-promise": "^1.0.0" } }, "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw=="],
@@ -3448,8 +3449,6 @@
"@modelcontextprotocol/sdk/zod-to-json-schema": ["zod-to-json-schema@3.24.5", "", { "peerDependencies": { "zod": "^3.24.1" } }, "sha512-/AuWwMP+YqiPbsJx5D6TfgRTc4kTLjsh5SOcd4bLsfUg2RcEXrFMJl1DGgdHy2aCfsIA/cr/1JM0xcB2GZji8g=="],
"@node-minify/core/glob": ["glob@10.3.3", "", { "dependencies": { "foreground-child": "^3.1.0", "jackspeak": "^2.0.3", "minimatch": "^9.0.1", "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0", "path-scurry": "^1.10.1" }, "bin": { "glob": "dist/cjs/src/bin.js" } }, "sha512-92vPiMb/iqpmEgsOoIDvTjc50wf9CCCvMzsi6W0JLPeUKE8TWP1a73PgqSrqy7iAZxaSD1YdzU7QZR5LF51MJw=="],
"@opennextjs/aws/express": ["express@5.2.1", "", { "dependencies": { "accepts": "^2.0.0", "body-parser": "^2.2.1", "content-disposition": "^1.0.0", "content-type": "^1.0.5", "cookie": "^0.7.1", "cookie-signature": "^1.2.1", "debug": "^4.4.0", "depd": "^2.0.0", "encodeurl": "^2.0.0", "escape-html": "^1.0.3", "etag": "^1.8.1", "finalhandler": "^2.1.0", "fresh": "^2.0.0", "http-errors": "^2.0.0", "merge-descriptors": "^2.0.0", "mime-types": "^3.0.0", "on-finished": "^2.4.1", "once": "^1.4.0", "parseurl": "^1.3.3", "proxy-addr": "^2.0.7", "qs": "^6.14.0", "range-parser": "^1.2.1", "router": "^2.2.0", "send": "^1.1.0", "serve-static": "^2.2.0", "statuses": "^2.0.1", "type-is": "^2.0.1", "vary": "^1.1.2" } }, "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw=="],
"@oxc-transform/binding-wasm32-wasi/@napi-rs/wasm-runtime": ["@napi-rs/wasm-runtime@1.1.1", "", { "dependencies": { "@emnapi/core": "^1.7.1", "@emnapi/runtime": "^1.7.1", "@tybys/wasm-util": "^0.10.1" } }, "sha512-p64ah1M1ld8xjWv3qbvFwHiFVWrq1yFvV4f7w+mzaqiR4IlSgkqhcRdHwsGgomwzBH51sRY4NEowLxnaBjcW/A=="],
@@ -3616,6 +3615,8 @@
"@vercel/backends/path-to-regexp": ["path-to-regexp@8.3.0", "", {}, "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA=="],
"@vercel/backends/resolve.exports": ["resolve.exports@2.0.3", "", {}, "sha512-OcXjMsGdhL4XnbShKpAcSqPMzQoYkYyhbEaeSko47MjRP9NfEQMhZkXL1DoFlt9LWQn4YttrdnV6X2OiyzBi+A=="],
"@vercel/backends/rolldown": ["rolldown@1.0.0-rc.1", "", { "dependencies": { "@oxc-project/types": "=0.110.0", "@rolldown/pluginutils": "1.0.0-rc.1" }, "optionalDependencies": { "@rolldown/binding-android-arm64": "1.0.0-rc.1", "@rolldown/binding-darwin-arm64": "1.0.0-rc.1", "@rolldown/binding-darwin-x64": "1.0.0-rc.1", "@rolldown/binding-freebsd-x64": "1.0.0-rc.1", "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.1", "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.1", "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.1", "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.1", "@rolldown/binding-linux-x64-musl": "1.0.0-rc.1", "@rolldown/binding-openharmony-arm64": "1.0.0-rc.1", "@rolldown/binding-wasm32-wasi": "1.0.0-rc.1", "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.1", "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.1" }, "bin": { "rolldown": "bin/cli.mjs" } }, "sha512-M3AeZjYE6UclblEf531Hch0WfVC/NOL43Cc+WdF3J50kk5/fvouHhDumSGTh0oRjbZ8C4faaVr5r6Nx1xMqDGg=="],
"@vercel/backends/zod": ["zod@3.22.4", "", {}, "sha512-iC+8Io04lddc+mVqQ9AZ7OQ2MrUKGN+oIQyq1vemgt46jwCwLfhq7/pwnBnNXXXZb8VTVLKwp9EDkx+ryxIWmg=="],
@@ -3790,8 +3791,6 @@
"finalhandler/encodeurl": ["encodeurl@1.0.2", "", {}, "sha512-TPJXq8JqFaVYm2CWmPvnP2Iyo4ZSM7/QKcSmuMLDObfpH5fi7RUGmd/rTDf+rut/saiDiQEeVTNgAmJEdAOx0w=="],
"foreground-child/cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
"global-prefix/which": ["which@1.3.1", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "which": "./bin/which" } }, "sha512-HxJdYWq1MTIQbJ3nw0cqssHoTNU267KlrDuGZ1WYlxDStUtKUhOaJmh112/TZmHxxUfuJqPXSOm7tDyas0OSIQ=="],
"globby/fast-glob": ["fast-glob@3.3.2", "", { "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", "glob-parent": "^5.1.2", "merge2": "^1.3.0", "micromatch": "^4.0.4" } }, "sha512-oX2ruAFQwf/Orj8m737Y5adxDQO0LAB7/S5MnxCdTNDd4p6BsyIVsv9JQsATbTSq8KHRpLwIHbVlUNatxd+1Ow=="],
@@ -4060,10 +4059,6 @@
"@jridgewell/source-map/@jridgewell/trace-mapping/@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.0", "", {}, "sha512-gv3ZRaISU3fjPAgNsriBRqGWQL6quFx04YMPW/zD8XMLsU32mhCCbfbO6KZFLjvYpCZ8zyDEgqsgf+PwPaM7GQ=="],
"@node-minify/core/glob/minimatch": ["minimatch@9.0.5", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow=="],
"@node-minify/core/glob/path-scurry": ["path-scurry@1.11.1", "", { "dependencies": { "lru-cache": "^10.2.0", "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0" } }, "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA=="],
"@opennextjs/aws/express/body-parser": ["body-parser@2.2.1", "", { "dependencies": { "bytes": "^3.1.2", "content-type": "^1.0.5", "debug": "^4.4.3", "http-errors": "^2.0.0", "iconv-lite": "^0.7.0", "on-finished": "^2.4.1", "qs": "^6.14.0", "raw-body": "^3.0.1", "type-is": "^2.0.1" } }, "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw=="],
"@opennextjs/aws/express/cookie": ["cookie@0.7.1", "", {}, "sha512-6DnInpx7SJ2AK3+CTUE/ZM0vWTUboZCegxhC2xiIydHR9jNuTAASBrfEpHhiGOZw/nX51bHt6YQl8jsGo4y/0w=="],
@@ -4426,10 +4421,6 @@
"remark-gfm/mdast-util-gfm/mdast-util-to-markdown": ["mdast-util-to-markdown@2.1.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "longest-streak": "^3.0.0", "mdast-util-phrasing": "^4.0.0", "mdast-util-to-string": "^4.0.0", "micromark-util-decode-string": "^2.0.0", "unist-util-visit": "^5.0.0", "zwitch": "^2.0.0" } }, "sha512-SR2VnIEdVNCJbP6y7kVTJgPLifdr8WEU440fQec7qHoHOUz/oJ2jmNRqdDQ3rbiStOXb2mCDGTuwsK5OPUgYlQ=="],
"rimraf/glob/foreground-child": ["foreground-child@3.3.0", "", { "dependencies": { "cross-spawn": "^7.0.0", "signal-exit": "^4.0.1" } }, "sha512-Ld2g8rrAyMYFXBhEqMz8ZAHBi4J4uS1i/CxGMDnjyFWddMXLVcDp051DZfu+t7+ab7Wv6SMqpWmyFIj5UbfFvg=="],
"rimraf/glob/jackspeak": ["jackspeak@3.4.3", "", { "dependencies": { "@isaacs/cliui": "^8.0.2" }, "optionalDependencies": { "@pkgjs/parseargs": "^0.11.0" } }, "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw=="],
"rimraf/glob/minimatch": ["minimatch@9.0.5", "", { "dependencies": { "brace-expansion": "^2.0.1" } }, "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow=="],
"rimraf/glob/minipass": ["minipass@7.1.2", "", {}, "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw=="],
@@ -4482,12 +4473,6 @@
"@headlessui/react/@floating-ui/react/@floating-ui/react-dom/@floating-ui/dom": ["@floating-ui/dom@1.7.5", "", { "dependencies": { "@floating-ui/core": "^1.7.4", "@floating-ui/utils": "^0.2.10" } }, "sha512-N0bD2kIPInNHUHehXhMke1rBGs1dwqvC9O9KYMyyjK7iXt7GAhnro7UlcuYcGdS/yYOlq0MAVgrow8IbWJwyqg=="],
"@node-minify/core/glob/minimatch/brace-expansion": ["brace-expansion@2.0.1", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA=="],
"@node-minify/core/glob/path-scurry/lru-cache": ["lru-cache@10.4.3", "", {}, "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ=="],
"@node-minify/core/glob/path-scurry/minipass": ["minipass@7.1.2", "", {}, "sha512-qOOzS1cBTWYF4BH8fVePDBOO9iptMnGUEZwNc/cMWnTV2nVLZ7VoNWEPHkYczZA0pdoA7dl6e7FL659nX9S2aw=="],
"@opennextjs/aws/express/body-parser/raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="],
"@opennextjs/aws/express/mime-types/mime-db": ["mime-db@1.53.0", "", {}, "sha512-oHlN/w+3MQ3rba9rqFr6V/ypF10LSkdwUysQL7GkXoTgIWeV+tcXGA852TBxH+gsh8UWoyhR1hKcoMJTuWflpg=="],
@@ -4570,8 +4555,6 @@
"@headlessui/react/@floating-ui/react/@floating-ui/react-dom/@floating-ui/dom/@floating-ui/core": ["@floating-ui/core@1.7.4", "", { "dependencies": { "@floating-ui/utils": "^0.2.10" } }, "sha512-C3HlIdsBxszvm5McXlB8PeOEWfBhcGBTZGkGlWc2U0KFY5IwG5OQEuQ8rq52DZmcHDlPLd+YFBK+cZcytwIFWg=="],
"@node-minify/core/glob/minimatch/brace-expansion/balanced-match": ["balanced-match@1.0.2", "", {}, "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="],
"@opennextjs/aws/express/body-parser/raw-body/http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="],
"@opennextjs/aws/express/qs/side-channel/object-inspect": ["object-inspect@1.13.4", "", {}, "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew=="],
+2 -2
View File
@@ -48,7 +48,7 @@
"@tsconfig/strictest": "^2.0.6",
"@tsconfig/node20": "^20.1.6",
"@base-ui/react": "^1.7.0",
"@gitbook/api": "0.208.0",
"@gitbook/api": "0.210.0",
"@scalar/api-client-react": "^1.3.46",
"@types/react": "^19.0.0",
"@types/react-dom": "^19.0.0",
@@ -68,7 +68,7 @@
"decode-named-character-reference@1.0.2": "patches/decode-named-character-reference@1.0.2.patch",
"@vercel/next@4.4.2": "patches/@vercel%2Fnext@4.4.2.patch",
"mermaid@11.16.1": "patches/mermaid@11.16.1.patch",
"next@16.4.5": "patches/next@16.4.5.patch",
"next@16.4.6": "patches/next@16.4.6.patch",
"@shikijs/langs@3.21.0": "patches/@shikijs%2Flangs@3.21.0.patch"
}
}
+6 -1
View File
@@ -127,6 +127,11 @@ frame.configure({
frame.on('close', () => {
console.log('Frame closed');
});
// Escape was pressed inside the frame and nothing in it (a menu, a dialog) used it
frame.on('escape', () => {
closeHelpPanel();
});
```
## As React components
@@ -222,7 +227,7 @@ function MyComponent() {
- `frame.postUserMessage(message: string)` → `void`
- `frame.clearChat()` → `void`
- `frame.configure(settings: Partial<GitBookEmbeddableConfiguration>)` → `void`
- `frame.on(event: string, listener: Function)` → `() => void` (unsubscribe)
- `frame.on(event: string, listener: Function)` → `() => void` (unsubscribe). Events: `close`, `escape`
### React Components
@@ -38,7 +38,10 @@ export type GitBookFrameClient = {
configure: (settings: Partial<GitBookEmbeddableConfiguration>) => void;
/**
* Register an event listener.
* Register an event listener and get back a function that removes it.
*
* - `close`: the built-in close button was clicked.
* - `escape`: Escape was pressed inside the frame and nothing in it (a menu, a dialog) used it.
*/
on: (event: string, listener: (...args: any[]) => void) => () => void;
};
@@ -64,11 +67,9 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
channel.receive((message: FrameToParentMessage) => {
console.log('[gitbook:embed] received message', message);
if (message.type === 'close') {
const listeners = events.get('close') || [];
if (listeners) {
listeners.forEach((listener) => listener());
}
if (message.type === 'close' || message.type === 'escape') {
const listeners = events.get(message.type) || [];
listeners.forEach((listener) => listener());
}
});
@@ -108,7 +109,7 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
return () => {
events.set(
event,
listeners.filter((l) => l !== listener)
(events.get(event) || []).filter((l) => l !== listener)
);
};
},
+8 -3
View File
@@ -137,6 +137,11 @@ export type ParentToFrameMessage =
/**
* Messages sent from the frame to the parent.
*/
export type FrameToParentMessage = {
type: 'close';
};
export type FrameToParentMessage =
| {
type: 'close';
}
| {
/** Escape was pressed inside the frame and nothing in the frame handled it. */
type: 'escape';
};
+2
View File
@@ -158,6 +158,8 @@
z-index: 9998;
width: calc(min(var(--gitbook-widget-window-width), calc(100vw - var(--gitbook-widget-right) - var(--gitbook-widget-left))));
height: calc(min(var(--gitbook-widget-window-height), calc(100vh - var(--gitbook-widget-window-bottom) - var(--gitbook-widget-top))));
/* stylelint-disable-next-line plugin/no-unsupported-browser-features -- the `vh` declaration above is the fallback on host pages whose browser lacks `dvh` */
height: calc(min(var(--gitbook-widget-window-height), calc(100dvh - var(--gitbook-widget-window-bottom) - var(--gitbook-widget-top))));
background-color: var(--gitbook-widget-background-translucent);
backdrop-filter: blur(48px);
border: 1px solid var(--gitbook-widget-border-color);
+821 -12
View File
@@ -1,4 +1,4 @@
import { type Page, expect } from '@playwright/test';
import { type Page, type Request, type Route, expect } from '@playwright/test';
import jwt from 'jsonwebtoken';
import {
@@ -16,7 +16,7 @@ import {
} from '@gitbook/api';
import type { GitBookStandalone } from '@gitbook/embed';
import { getGitBookPreviewURL, getSiteAPIToken } from '../tests/utils';
import { getContentTestURL, getGitBookPreviewURL, getSiteAPIToken } from '../tests/utils';
import {
type Test,
type TestsCase,
@@ -41,16 +41,15 @@ import {
import { VISITOR_TOKEN_COOKIE } from '@/lib/visitors';
// Kept as deterministic as possible to reduce visual flakiness: no preamble, a
// single fixed search, a concise answer, and a fixed number of follow-ups. The
// model is never perfectly deterministic, so `overrideAIResponse` still
// normalizes the rendered content below — this prompt just narrows the variance.
// single fixed search, and a concise answer. The model is never perfectly
// deterministic, so `overrideAIResponse` still normalizes the rendered content
// below — this prompt just narrows the variance.
const AI_PROMPT = [
"You're being invoked by the GitBook CI/CD pipeline for automated visual testing.",
'Follow these instructions exactly and do not deviate:',
'1. Do not write any preamble, commentary, or reasoning before acting.',
'2. Perform a single search for exactly "Lorem ipsum".',
'3. Reply with only the first sentence of the first page you find, and nothing else.',
'4. Always end by proposing exactly 3 follow-up suggestions.',
].join('\n');
// `InsightsProvider` debounces its flushes by 1.5s.
@@ -74,6 +73,62 @@ function trackInsightsEvents(page: Page, type: string) {
return collected;
}
/**
* Hold the page's search requests until the test answers them, and find a held one by query.
*/
async function holdSearchRequests(page: Page) {
// Without a pass every search goes through the route, whether or not the site's flag gives one.
await page.route('**/~gitbook/search-pass', (route) => route.fulfill({ status: 204 }));
const held: Route[] = [];
await page.route('**/~gitbook/search', (route) => {
held.push(route);
});
return async (query: string) => {
await expect
.poll(() => held.some((route) => route.request().postDataJSON().query === query))
.toBe(true);
const index = held.findIndex((route) => route.request().postDataJSON().query === query);
const [route] = held.splice(index, 1);
if (!route) {
throw new Error(`No held search for "${query}"`);
}
return route;
};
}
/**
* Answer a held search request with the server's own answer, and return its top result.
*/
async function answerSearch(route: Route) {
const response = await route.fetch();
const [topResult]: { title: string; href: string }[] = await response.json();
await route.fulfill({ response });
if (!topResult) {
throw new Error('The search answer has no results');
}
return topResult;
}
/**
* Build a page result for a search answer given by the test.
*/
function searchPageResult(route: Route, siteSpaceId: string, title: string, path: string) {
const sitePath = new URL(route.request().url()).pathname.replace('~gitbook/search', '');
return {
type: 'page',
id: `space/${title}`,
pageId: title,
spaceId: 'space',
siteSpaceId,
title,
description: '',
href: `${sitePath}${path}`,
score: 1,
rank: 1,
};
}
const overrideAIInitialState = () => {
const greeting = document.querySelector('[data-testid="ai-chat-greeting-title"]');
if (greeting) {
@@ -158,6 +213,29 @@ const searchTestCases: Test[] = [
await expect(page.getByTestId('search-input')).toBeFocused();
},
},
{
name: 'Search - Loading rows cannot be activated',
url: getCustomizationURL({
ai: {
mode: CustomizationAIMode.None,
},
}),
screenshot: false,
run: async (page) => {
await waitForCookiesDialog(page);
const heldSearch = await holdSearchRequests(page);
const searchInput = page.getByTestId('search-input');
await searchInput.focus();
await page.waitForURL(/[?&]q=/);
await searchInput.pressSequentially('gitbook');
await heldSearch('gitbook');
const searchPopup = page.getByTestId('search-popover');
await expect(searchPopup.locator('[aria-busy="true"]').first()).toBeVisible();
await expect(searchPopup.getByTestId('search-page-result')).toHaveCount(0);
await expect(searchPopup.getByRole('link')).toHaveCount(0);
},
},
{
name: 'Search - Keyboard focus exits to the next page control',
url: getCustomizationURL({
@@ -209,6 +287,48 @@ const searchTestCases: Test[] = [
await expect(searchInput).toHaveValue('getting started');
},
},
{
name: 'Search - Retry after a failed search sends the query once',
url: getCustomizationURL({
ai: {
mode: CustomizationAIMode.None,
},
header: {
preset: CustomizationHeaderPreset.None,
},
}),
screenshot: false,
run: async (page) => {
await waitForCookiesDialog(page);
// Keep the search on the failing route whether or not the site gives search passes.
await page.route('**/~gitbook/search-pass', (route) => route.fulfill({ status: 204 }));
let failing = true;
await page.route('**/~gitbook/search', (route) =>
failing ? route.fulfill({ status: 500 }) : route.continue()
);
const sentQueries: string[] = [];
page.on('request', (request) => {
if (request.method() === 'POST' && request.url().endsWith('/~gitbook/search')) {
sentQueries.push(request.postDataJSON().query);
}
});
const searchInput = page.getByTestId('search-input').locator('visible=true');
await searchInput.focus();
await page.waitForURL(/[?&]q=/);
await searchInput.pressSequentially('gitbook');
const retry = page.getByRole('button', { name: 'Try again' }).locator('visible=true');
await expect(retry).toBeVisible();
failing = false;
sentQueries.length = 0;
await retry.click();
await expect(searchInput).toHaveValue('gitbook');
await expect(page.getByTestId('search-results').locator('visible=true')).toBeVisible();
await page.waitForTimeout(1000);
expect(sentQueries).toEqual(['gitbook']);
},
},
{
name: 'Search - AI Mode: None - URL query (Initial)',
url: `${getCustomizationURL({
@@ -286,6 +406,68 @@ const searchTestCases: Test[] = [
expect(top).toBeLessThanOrEqual(150);
},
},
{
name: 'Search - Enter while results load opens the top result of the last query',
url: `blocks/lists${getCustomizationURL({
ai: {
mode: CustomizationAIMode.None,
},
})}`,
screenshot: false,
run: async (page) => {
await waitForCookiesDialog(page);
const heldSearch = await holdSearchRequests(page);
const startPath = new URL(page.url()).pathname;
const searchInput = page.getByTestId('search-input');
await searchInput.focus();
await page.waitForURL(/[?&]q=/);
await searchInput.pressSequentially('gitbook');
const firstSearch = await heldSearch('gitbook');
await searchInput.selectText();
await searchInput.pressSequentially('files');
const lastSearch = await heldSearch('files');
await page.keyboard.press('Enter');
await answerSearch(firstSearch).catch(() => {});
await page.waitForTimeout(1000);
await expect(page.getByTestId('search-popover')).toBeVisible();
await expect(searchInput).toBeFocused();
expect(new URL(page.url()).pathname).toBe(startPath);
const topResult = await answerSearch(lastSearch);
await expect(
page.getByRole('heading', { level: 1, name: topResult.title, exact: true })
).toBeVisible({ timeout: 20000 });
expect(new URL(page.url()).pathname).toBe(new URL(topResult.href, page.url()).pathname);
},
},
{
name: 'Search - Enter opens the result under the mouse',
url: `blocks/lists${getCustomizationURL({
ai: {
mode: CustomizationAIMode.None,
},
})}`,
screenshot: false,
run: async (page) => {
await waitForCookiesDialog(page);
const searchInput = page.getByTestId('search-input');
await searchInput.focus();
await searchInput.pressSequentially('gitbook');
const searchPopup = page.getByTestId('search-popover');
const hovered = searchPopup.getByTestId('search-page-result').nth(1);
await hovered.hover();
await expect(hovered).toHaveClass(/is-active/);
await expect(searchPopup.locator('[role="option"].is-active')).toHaveCount(1);
const href = await hovered.getAttribute('href');
await page.keyboard.press('Enter');
await expect
.poll(() => new URL(page.url()).pathname, { timeout: 20000 })
.toBe(new URL(href ?? '', page.url()).pathname);
},
},
{
name: 'Ask - AI Mode: Assistant - Complete flow',
url: getCustomizationURL({
@@ -306,10 +488,9 @@ const searchTestCases: Test[] = [
await expect(page.getByTestId('ai-chat')).toBeVisible();
await expect(page.getByTestId('ai-chat-message-user').first()).toHaveText(AI_PROMPT);
await expect(page.getByTestId('ai-chat-message-assistant').first()).toBeVisible();
// Wait for the full response (incl. follow-up suggestions) to settle before
// asserting/screenshotting, rather than racing a fixed suggestion count.
// Wait for the stream, follow-up phase included, to finish before screenshotting.
// Follow-ups aren't asserted: the API can return none for this prompt.
await waitForAIChatResponse(page);
await expect(page.getByTestId('ai-chat-followup-suggestion').first()).toBeVisible();
},
// Re-applied per viewport so the replacement survives resize-driven re-renders.
normalizeBeforeScreenshot: (page) => page.evaluate(overrideAIResponse),
@@ -377,16 +558,553 @@ const searchTestCases: Test[] = [
await expect(page.getByTestId('ai-chat')).toBeVisible();
await expect(page.getByTestId('ai-chat-message-user').first()).toHaveText(AI_PROMPT);
await expect(page.getByTestId('ai-chat-message-assistant').first()).toBeVisible();
// Wait for the full response (incl. follow-up suggestions) to settle before
// asserting/screenshotting, rather than racing a fixed suggestion count.
// Wait for the stream, follow-up phase included, to finish before screenshotting.
// Follow-ups aren't asserted: the API can return none for this prompt.
await waitForAIChatResponse(page);
await expect(page.getByTestId('ai-chat-followup-suggestion').first()).toBeVisible();
},
// Re-applied per viewport so the replacement survives resize-driven re-renders.
normalizeBeforeScreenshot: (page) => page.evaluate(overrideAIResponse),
},
];
const SEARCH_API_URL = /\/v1\/orgs\/[^/]+\/sites\/[^/]+\/search$/;
const SEARCH_PASS_RECORD = {
type: 'record',
id: 'search-pass-record',
title: 'Answered by the search API',
description: 'A search made with a search pass',
url: 'https://example.com/search-pass',
score: 1,
};
/**
* Answer the page's search pass requests as the API does when passes are switched on.
*/
async function giveSearchPasses(page: Page, lifetimesMs: number[] = []) {
let passes = 0;
await page.route('**/~gitbook/search-pass', async (route) => {
passes += 1;
await route.fulfill({
json: {
token: `test-search-pass-${passes}`,
expiresIn: lifetimesMs.shift() ?? 300_000,
},
});
});
}
/**
* Answer each search API call with the next status, and with a record when it succeeds.
*/
async function answerSearchAPI(page: Page, statuses: number[] = []) {
const calls: Request[] = [];
await page.route(SEARCH_API_URL, async (route) => {
calls.push(route.request());
const status = statuses.shift() ?? 200;
await route.fulfill({
status,
headers: { 'access-control-allow-origin': '*' },
json: status === 200 ? { items: [SEARCH_PASS_RECORD] } : { error: { code: status } },
});
});
return calls;
}
/**
* Collect the searches the page sends to the site's search route.
*/
function trackRouteSearches(page: Page) {
const searches: Request[] = [];
page.on('request', (request) => {
if (request.method() === 'POST' && request.url().endsWith('/~gitbook/search')) {
searches.push(request);
}
});
return searches;
}
/**
* Open search and wait for the page to receive its search pass.
*/
async function openSearchWithPass(page: Page) {
const passReply = page.waitForResponse('**/~gitbook/search-pass');
await page.getByTestId('search-input').focus();
await passReply;
}
async function typeSearch(page: Page, text: string) {
const searchInput = page.getByTestId('search-input');
await searchInput.focus();
await searchInput.pressSequentially(text);
}
const searchPassTestCases: Test[] = [
{
name: 'No pass: searches go through the site route',
url: '',
screenshot: false,
run: async (page) => {
await page.route('**/~gitbook/search-pass', (route) => route.fulfill({ status: 204 }));
const passReply = page.waitForResponse('**/~gitbook/search-pass');
const apiCalls: Request[] = [];
page.on('request', (request) => {
if (SEARCH_API_URL.test(request.url())) {
apiCalls.push(request);
}
});
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await typeSearch(page, 'gitbook');
expect((await passReply).status()).toBe(204);
await expect
.poll(() => routeSearches.length, { timeout: 30_000 })
.toBeGreaterThanOrEqual(1);
expect((await routeSearches[0]?.response())?.status()).toBe(200);
expect(apiCalls).toHaveLength(0);
},
},
{
name: 'With a pass: searches go straight to the API',
url: '',
screenshot: false,
run: async (page) => {
await giveSearchPasses(page);
const apiCalls = await answerSearchAPI(page);
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await openSearchWithPass(page);
await typeSearch(page, 'gitbook');
await expect(
page
.getByTestId('search-record-result')
.filter({ hasText: SEARCH_PASS_RECORD.title })
).toBeVisible({ timeout: 30_000 });
expect((await apiCalls[0]?.allHeaders())?.authorization).toBe(
'Bearer test-search-pass-1'
);
expect(routeSearches).toHaveLength(0);
},
},
{
name: 'Expired pass: the search uses the route, then the next pass searches the API',
url: '',
screenshot: false,
run: async (page) => {
await giveSearchPasses(page, [1_000]);
const apiCalls = await answerSearchAPI(page);
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await openSearchWithPass(page);
await typeSearch(page, 'gitbook');
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(1);
expect(routeSearches[0]?.headers()['x-gitbook-search-fallback']).toBe('expired');
expect(apiCalls).toHaveLength(0);
await typeSearch(page, ' editor');
await expect(
page
.getByTestId('search-record-result')
.filter({ hasText: SEARCH_PASS_RECORD.title })
).toBeVisible({ timeout: 30_000 });
expect((await apiCalls[0]?.allHeaders())?.authorization).toBe(
'Bearer test-search-pass-2'
);
},
},
{
name: 'Refused pass: the page stays on the route',
url: '',
screenshot: false,
run: async (page) => {
await giveSearchPasses(page);
const apiCalls = await answerSearchAPI(page, [403]);
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await openSearchWithPass(page);
await typeSearch(page, 'gitbook');
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(1);
await typeSearch(page, ' editor');
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(2);
expect(
routeSearches.map((request) => request.headers()['x-gitbook-search-fallback'])
).toEqual(['403', '403']);
expect(apiCalls).toHaveLength(1);
expect((await routeSearches.at(-1)?.response())?.status()).toBe(200);
},
},
{
name: 'Dropped API request: the search falls back to the route after its time limit',
url: '',
screenshot: false,
run: async (page) => {
await page.clock.install();
await giveSearchPasses(page);
const apiCalls: Request[] = [];
await page.route(SEARCH_API_URL, (route) => {
apiCalls.push(route.request());
});
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await openSearchWithPass(page);
await typeSearch(page, 'gitbook');
await expect.poll(() => apiCalls.length, { timeout: 30_000 }).toBe(1);
await page.clock.fastForward(5_000);
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(1);
expect(routeSearches[0]?.headers()['x-gitbook-search-fallback']).toBe('timeout');
expect((await routeSearches[0]?.response())?.status()).toBe(200);
await typeSearch(page, ' editor');
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(2);
expect(apiCalls).toHaveLength(1);
},
},
{
name: 'Withdrawn pass: a no-pass reply stops the page using the earlier pass',
url: '',
screenshot: false,
run: async (page) => {
let passReplies = 0;
await page.route('**/~gitbook/search-pass', async (route) => {
passReplies += 1;
await (passReplies === 1
? route.fulfill({ json: { token: 'test-search-pass-1', expiresIn: 300_000 } })
: route.fulfill({ status: 204 }));
});
const apiCalls = await answerSearchAPI(page);
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await openSearchWithPass(page);
await typeSearch(page, 'gitbook');
await expect(
page
.getByTestId('search-record-result')
.filter({ hasText: SEARCH_PASS_RECORD.title })
).toBeVisible({ timeout: 30_000 });
await page.keyboard.press('Escape');
await openSearchWithPass(page);
await typeSearch(page, ' editor');
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(1);
expect(apiCalls).toHaveLength(1);
},
},
{
name: 'Rejected replacement pass: the page stays on the route after one refresh',
url: '',
screenshot: false,
run: async (page) => {
await giveSearchPasses(page);
const passRequests: Request[] = [];
page.on('request', (request) => {
if (request.url().endsWith('/~gitbook/search-pass')) {
passRequests.push(request);
}
});
const apiCalls = await answerSearchAPI(page, [401, 401, 401, 401]);
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await openSearchWithPass(page);
for (const [index, text] of ['gitbook', ' editor', ' blocks', ' lists'].entries()) {
await typeSearch(page, text);
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(index + 1);
await page.waitForTimeout(500);
}
expect(apiCalls).toHaveLength(2);
expect(passRequests).toHaveLength(2);
},
},
{
name: 'Rate limited: the next query waits for the cooldown before using the route',
url: '',
screenshot: false,
run: async (page) => {
await giveSearchPasses(page);
const apiCalls = await answerSearchAPI(page, [429]);
const routeSearchTimes: number[] = [];
page.on('request', (request) => {
if (request.method() === 'POST' && request.url().endsWith('/~gitbook/search')) {
routeSearchTimes.push(Date.now());
}
});
await waitForCookiesDialog(page);
await openSearchWithPass(page);
const rateLimited = page.waitForResponse(SEARCH_API_URL);
await typeSearch(page, 'gitbook');
await rateLimited;
const rateLimitedAt = Date.now();
await typeSearch(page, ' editor');
await expect.poll(() => routeSearchTimes.length, { timeout: 30_000 }).toBe(1);
expect(routeSearchTimes[0]! - rateLimitedAt).toBeGreaterThanOrEqual(1_500);
expect(apiCalls).toHaveLength(1);
},
},
{
name: 'Renewing pass: a search typed before the reply goes to the route',
url: '',
screenshot: false,
run: async (page) => {
let releaseRenewal = () => {};
const renewalHeld = new Promise<void>((resolve) => {
releaseRenewal = resolve;
});
let passReplies = 0;
await page.route('**/~gitbook/search-pass', async (route) => {
passReplies += 1;
if (passReplies === 1) {
await route.fulfill({
json: { token: 'test-search-pass-1', expiresIn: 300_000 },
});
return;
}
await renewalHeld;
await route.fulfill({ status: 204 }).catch(() => undefined);
});
const apiCalls = await answerSearchAPI(page);
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await openSearchWithPass(page);
await typeSearch(page, 'gitbook');
await expect.poll(() => apiCalls.length, { timeout: 30_000 }).toBe(1);
await page.keyboard.press('Escape');
const renewal = page.waitForRequest('**/~gitbook/search-pass');
await typeSearch(page, ' editor');
await renewal;
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(1);
expect(apiCalls).toHaveLength(1);
releaseRenewal();
},
},
{
name: 'Rate limited by a shared limit: searches fail at once until its reset',
url: '',
screenshot: false,
run: async (page) => {
await giveSearchPasses(page);
const apiCalls: Request[] = [];
await page.route(SEARCH_API_URL, async (route) => {
apiCalls.push(route.request());
await route.fulfill({
status: 429,
headers: {
'access-control-allow-origin': '*',
'access-control-expose-headers': 'x-ratelimit-reset, x-ratelimit-scope',
'x-ratelimit-reset': String(Math.ceil(Date.now() / 1000) + 60),
'x-ratelimit-scope': 'tenant-operation',
},
json: { error: { code: 429 } },
});
});
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
await openSearchWithPass(page);
await typeSearch(page, 'gitbook');
await expect.poll(() => apiCalls.length, { timeout: 30_000 }).toBe(1);
await typeSearch(page, ' editor');
await expect(page.getByRole('button', { name: 'Try again' })).toBeVisible({
timeout: 30_000,
});
await page.waitForTimeout(3_000);
expect(routeSearches).toHaveLength(0);
expect(apiCalls).toHaveLength(1);
},
},
{
name: 'Cancelled search: a late API answer never replaces the newer query',
url: '',
screenshot: false,
run: async (page) => {
await giveSearchPasses(page);
const staleTitle = 'Late answer for an older query';
await page.route(SEARCH_API_URL, async (route) => {
const { query } = route.request().postDataJSON() as { query: string };
const stale = query === 'gitbook';
if (stale) {
await page.waitForTimeout(3_000);
}
await route
.fulfill({
headers: { 'access-control-allow-origin': '*' },
json: {
items: [
stale
? { ...SEARCH_PASS_RECORD, title: staleTitle }
: SEARCH_PASS_RECORD,
],
},
})
.catch(() => undefined);
});
const routeSearches = trackRouteSearches(page);
await waitForCookiesDialog(page);
const firstSearch = page.waitForRequest(
(request) =>
SEARCH_API_URL.test(request.url()) &&
(request.postDataJSON() as { query: string }).query === 'gitbook'
);
await openSearchWithPass(page);
await typeSearch(page, 'gitbook');
await firstSearch;
await typeSearch(page, ' editor');
await expect(
page
.getByTestId('search-record-result')
.filter({ hasText: SEARCH_PASS_RECORD.title })
).toBeVisible({ timeout: 30_000 });
await page.waitForTimeout(4_000);
await expect(page.getByText(staleTitle)).toHaveCount(0);
expect(routeSearches).toHaveLength(0);
},
},
{
name: 'Embedded search goes straight to the API',
url: '~gitbook/embed/search',
screenshot: false,
run: async (page) => {
await giveSearchPasses(page);
await answerSearchAPI(page);
const routeSearches = trackRouteSearches(page);
// The embedded page keeps <html> hidden, so wait for hydration without visibility.
await page.locator('html.hydrated').waitFor({ state: 'attached' });
// The embedded search opens on the first key; a one-letter query is never sent.
const passReply = page.waitForResponse('**/~gitbook/search-pass');
await typeSearch(page, 'g');
await passReply;
await typeSearch(page, 'itbook');
await expect(
page
.getByTestId('search-record-result')
.filter({ hasText: SEARCH_PASS_RECORD.title })
).toBeVisible({ timeout: 30_000 });
// The one-letter query can reach the route when it is sent before the pass arrives.
const routeQueries = routeSearches.map((request) => request.postDataJSON().query);
expect(routeQueries).not.toContain('gitbook');
},
},
];
const VISITOR_AUTH_SITE = 'https://gitbook.gitbook.io/gbo-va-space/';
function signVisitorToken(name: string) {
return jwt.sign({ name }, '70b844d0-c519-4532-8586-5970ce48c537', { expiresIn: '24h' });
}
/**
* Give the page one search pass, then answer later pass requests with `later` or the site's route.
*/
async function giveOneSearchPass(page: Page, later?: { token: string }) {
let passes = 0;
await page.route('**/~gitbook/search-pass', async (route) => {
passes += 1;
if (passes > 1 && !later) {
await route.continue();
return;
}
await route.fulfill({
json: {
token: passes === 1 ? 'test-search-pass-1' : later?.token,
expiresIn: 300_000,
},
});
});
}
/**
* Open a second tab of the site at `path`, keeping it from leaving for an upstream sign-in page.
*/
async function visitInOtherTab(page: Page, path: string) {
const other = await page.context().newPage();
await other.route(
(url) => url.hostname !== new URL(page.url()).hostname,
(route) => route.abort()
);
await other.goto(getContentTestURL(new URL(path, VISITOR_AUTH_SITE).href), {
waitUntil: 'commit',
});
await other.close();
}
/**
* Close search and open it again, waiting for the pass request that opening sends.
*/
async function reopenSearch(page: Page) {
await page.keyboard.press('Escape');
const passReply = page.waitForResponse('**/~gitbook/search-pass');
await page.getByTestId('search-input').focus();
return passReply;
}
const searchPassSessionTestCases: Test[] = [
{
name: 'Signed out in another tab: reopening search drops the pass',
url: () => `first?jwt_token=${signVisitorToken('gitbook-open-tests')}`,
screenshot: false,
run: async (page) => {
await giveOneSearchPass(page);
const apiCalls = await answerSearchAPI(page);
const routeSearches = trackRouteSearches(page);
await waitForHydration(page);
await openSearchWithPass(page);
await typeSearch(page, 'first');
await expect.poll(() => apiCalls.length, { timeout: 30_000 }).toBe(1);
await visitInOtherTab(page, '~gitbook/auth/logout');
await expect
.poll(async () =>
(await page.context().cookies()).some((cookie) =>
cookie.name.startsWith(VISITOR_TOKEN_COOKIE)
)
)
.toBe(false);
expect((await reopenSearch(page)).status()).toBe(401);
await typeSearch(page, ' page');
await expect.poll(() => routeSearches.length, { timeout: 30_000 }).toBe(1);
expect(apiCalls).toHaveLength(1);
},
},
{
name: 'Signed in as another visitor in another tab: reopening search uses the new pass',
url: () => `first?jwt_token=${signVisitorToken('gitbook-open-tests')}`,
screenshot: false,
run: async (page) => {
await giveOneSearchPass(page, { token: 'test-search-pass-2' });
const apiCalls = await answerSearchAPI(page);
await waitForHydration(page);
await openSearchWithPass(page);
await typeSearch(page, 'first');
await expect.poll(() => apiCalls.length, { timeout: 30_000 }).toBe(1);
const otherVisitor = signVisitorToken('another-visitor');
await visitInOtherTab(page, `first?jwt_token=${otherVisitor}`);
const passReply = await reopenSearch(page);
expect((await passReply.request().allHeaders()).cookie).toContain(otherVisitor);
await typeSearch(page, ' page');
await expect.poll(() => apiCalls.length, { timeout: 30_000 }).toBe(2);
expect((await apiCalls[1]?.allHeaders())?.authorization).toBe(
'Bearer test-search-pass-2'
);
},
},
];
const testCases: TestsCase[] = [
{
name: 'GitBook Site (Single Variant)',
@@ -480,6 +1198,59 @@ const testCases: TestsCase[] = [
await spaceDrowpdown.waitFor();
},
},
{
name: 'Search scope change while loading shows the new answer in server order',
url: '',
screenshot: false,
run: async (page) => {
await waitForHydration(page);
const heldSearch = await holdSearchRequests(page);
const searchInput = page.getByTestId('search-input');
await searchInput.focus();
await page.waitForURL(/[?&]q=/);
await searchInput.pressSequentially('quick');
const variantSearch = await heldSearch('quick');
const searchPopup = page.getByTestId('search-popover');
await searchPopup.getByRole('button', { name: 'Multi-Variants' }).click();
await page.getByRole('menuitem', { name: /All content/ }).click();
const allContentSearch = await heldSearch('quick');
const variantScope = variantSearch.request().postDataJSON().scope;
expect(allContentSearch.request().postDataJSON().scope).not.toEqual(
variantScope
);
const { siteSpaceId } = variantScope;
await allContentSearch.fulfill({
json: [
searchPageResult(allContentSearch, siteSpaceId, 'Welcome!', ''),
searchPageResult(
allContentSearch,
siteSpaceId,
'Quick Start',
'quick-start'
),
],
});
await variantSearch
.fulfill({
json: [
searchPageResult(
variantSearch,
siteSpaceId,
'Quick Start',
'quick-start'
),
],
})
.catch(() => {});
const results = searchPopup.getByTestId('search-page-result');
await expect(results).toHaveText([/Welcome!/, /Quick Start/]);
await page.waitForTimeout(1000);
await expect(results).toHaveText([/Welcome!/, /Quick Start/]);
},
},
{
name: 'Default variant',
url: '',
@@ -1177,6 +1948,16 @@ const testCases: TestsCase[] = [
contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
tests: searchTestCases,
},
{
name: 'Search pass',
contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
tests: searchPassTestCases,
},
{
name: 'Search pass with visitor authentication',
contentBaseURL: VISITOR_AUTH_SITE,
tests: searchPassSessionTestCases,
},
{
name: 'Content tests',
contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/',
@@ -2987,6 +3768,34 @@ const testCases: TestsCase[] = [
},
],
},
{
name: 'Docs Embed - Search',
contentBaseURL: 'https://gitbook.gitbook.io/test-gitbook-open/~gitbook/embed/',
tests: [
{
name: 'Enter while results load opens the top result',
url: 'search',
screenshot: false,
run: async (page) => {
await page.waitForLoadState('load');
const heldSearch = await holdSearchRequests(page);
const searchInput = page.getByTestId('search-input');
await searchInput.pressSequentially('files');
const search = await heldSearch('files');
await searchInput.press('Enter');
await page.waitForTimeout(1000);
await expect(searchInput).toBeFocused();
await expect(page.getByTestId('embed-docs-page')).toHaveCount(0);
const topResult = await answerSearch(search);
await expect(
page.getByRole('heading', { level: 1, name: topResult.title, exact: true })
).toBeVisible({ timeout: 20000 });
},
},
],
},
];
runTestCases(testCases);
+12
View File
@@ -1,6 +1,7 @@
// @ts-check
import { networkInterfaces } from 'node:os';
import { fileURLToPath } from 'node:url';
// Next blocks its dev client and HMR when a physical device opens the server over a LAN address.
// Needed to hydrate the dev client on physical phones/tablets over the internal network
@@ -119,6 +120,17 @@ const nextConfig = {
],
},
webpack(config, { isServer }) {
if (isServer) {
// mcp-handler only needs redis for SSE, which we disable: keep the client out of the server bundle.
config.resolve.alias = {
...config.resolve.alias,
redis$: fileURLToPath(new URL('./src/lib/mcp/redis-stub.ts', import.meta.url)),
};
}
return config;
},
async headers() {
return [
{
@@ -3,6 +3,7 @@
"name": "gitbook-open-v2",
"compatibility_date": "2026-04-02",
"keep_names": false,
"minify": true,
"compatibility_flags": [
"nodejs_compat",
"allow_importable_env",
@@ -0,0 +1,23 @@
import { describe, expect, it } from 'bun:test';
import { createHash } from 'node:crypto';
import { GitbookIncrementalCache } from './incrementalCache';
describe('GitbookIncrementalCache.getR2Key', () => {
const cache = new GitbookIncrementalCache();
it('accepts the hashed composable key passed by OpenNext', () => {
const storageKey = createHash('sha256').update('["build-id","action",[]]').digest('hex');
const key = cache.getR2Key(storageKey, 'composable');
const hash = createHash('sha256').update(storageKey).digest('hex');
expect(key).toBe(`incremental-cache/dataCache/${hash}.composable`);
});
it('maps distinct composable keys to distinct R2 keys', () => {
expect(cache.getR2Key('a'.repeat(64), 'composable')).not.toBe(
cache.getR2Key('b'.repeat(64), 'composable')
);
});
});
@@ -118,15 +118,8 @@ export class GitbookIncrementalCache implements IncrementalCache {
}
}
// Utility function to generate keys for R2/Cache API
getR2Key(initialKey: string, cacheType: CacheEntryType = 'cache'): string {
let key = initialKey;
if (cacheType === 'composable') {
// For composable cache, we need to discard the build ID from the key
const [_buildId, ...restOfTheKey] = JSON.parse(initialKey);
key = JSON.stringify([...restOfTheKey]);
}
// OpenNext pre-hashes composable keys with the build ID in them: no reuse across deploys.
getR2Key(key: string, cacheType: CacheEntryType = 'cache'): string {
const hash = createHash('sha256').update(key).digest('hex');
return `${DEFAULT_PREFIX}/${cacheType === 'cache' ? process.env?.NEXT_BUILD_ID : 'dataCache'}/${hash}.${cacheType}`.replace(
/\/+/g,
+5 -4
View File
@@ -20,8 +20,8 @@
"@gitbook/react-openapi": "workspace:*",
"@mermaid-js/mermaid-zenuml": "^0.2.2",
"@modelcontextprotocol/sdk": "1.17.5",
"@opennextjs/aws": "4.1.15",
"@opennextjs/cloudflare": "1.20.16",
"@opennextjs/aws": "4.1.16",
"@opennextjs/cloudflare": "1.20.17",
"@panzoom/panzoom": "^4.6.1",
"@sindresorhus/fnv1a": "^3.1.0",
"@tailwindcss/container-queries": "^0.1.1",
@@ -51,7 +51,7 @@
"micromark-extension-gfm": "^3.0.0",
"motion": "^12.23.24",
"negotiator": "^1.0.0",
"next": "^16.4.5",
"next": "^16.4.6",
"next-themes": "^0.4.6",
"nuqs": "^2.2.3",
"object-hash": "^3.0.0",
@@ -59,6 +59,7 @@
"openapi-types": "^12.1.3",
"p-map": "^7.0.3",
"p-retry": "^8.0.0",
"parse5": "7.2.0",
"quick-lru": "^7.0.1",
"react": "19.2.4",
"react-dom": "19.2.4",
@@ -135,7 +136,7 @@
"e2e": "playwright test e2e/internal.spec.ts e2e/cookie-banner.spec.ts e2e/pdf.spec.ts e2e/select.spec.ts e2e/tabs-overflow.spec.ts --project=chromium",
"e2e-customers": "playwright test e2e/customers.spec.ts --project=chromium",
"e2e-style-perf": "playwright test e2e/style-perf.spec.ts --project=chromium --reporter=list",
"unit": "bun run generate:assets && bun test {src,packages} --preload ./tests/preload-bun.ts",
"unit": "bun run generate:assets && bun test {src,packages,openNext} --preload ./tests/preload-bun.ts",
"e2e-browserless": "bun test ./tests/",
"typecheck": "tsc --noEmit"
},
@@ -50,6 +50,7 @@ export async function handleMcpRequest(
streamableHttpEndpoint: context.linker.toPathInSite(endpoint),
maxDuration: 60,
verboseLogs: true,
// SSE needs redis, which next.config.mjs stubs out of the server bundle.
disableSse: true,
}
);
@@ -1,16 +1,18 @@
import { type NextRequest, NextResponse } from 'next/server';
import { orderSearchResultGroups } from './orderSearchResults';
import type {
OrderedComputedResult,
SearchSiteContentRequest,
} from '@/components/Search/search-types';
import { SEARCH_FALLBACK_HEADER } from '@/components/Search/search-pass-store';
import type { SearchSiteContentRequest } from '@/components/Search/search-types';
import { throwIfDataError } from '@/lib/data';
import { getLogger } from '@/lib/logger';
import { getSiteURLDataFromMiddleware } from '@/lib/middleware';
import { transformSitePageResult } from '@/lib/search';
import { computeSearchResults } from '@/lib/search-results';
import { getServerActionBaseContext } from '@/lib/server-actions';
import { findSiteSpaceBy, getLinkerForSiteSpace } from '@/lib/sites';
const SEARCH_FALLBACK_REASON =
/^(\d{3}|expired|pass_request|network|timeout|invalid|unknown_space)$/;
export async function POST(request: NextRequest) {
const { asEmbeddable, query, scope } = (await request.json()) as SearchSiteContentRequest;
const [context, siteURLData] = await Promise.all([
@@ -18,6 +20,15 @@ export async function POST(request: NextRequest) {
getSiteURLDataFromMiddleware(),
]);
const fallback = request.headers.get(SEARCH_FALLBACK_HEADER);
if (fallback && SEARCH_FALLBACK_REASON.test(fallback)) {
getLogger()
.subLogger('search')
.info(
`Search pass fallback to the route (reason=${fallback}, organization=${siteURLData.organization}, site=${siteURLData.site})`
);
}
if (query.length <= 1) {
return NextResponse.json([]);
}
@@ -56,49 +67,24 @@ export async function POST(request: NextRequest) {
? getLinkerForSiteSpace(context.linker, currentSiteSpace.siteSpace, revision.pages)
: context.linker;
const results = orderSearchResultGroups<OrderedComputedResult>(
searchResults.map((resultItem) => {
if (resultItem.type === 'record') {
const result: OrderedComputedResult = {
type: 'record',
id: resultItem.id,
title: resultItem.title,
description: resultItem.description,
href: resultItem.url,
score: resultItem.score,
};
const results = computeSearchResults(searchResults, (spaceItem, pageItem) => {
const isCurrentRevisionSpace = Boolean(revision && spaceItem.id === siteURLData.space);
const found =
isCurrentRevisionSpace && currentSiteSpace
? currentSiteSpace
: findSiteSpaceBy(structure, (siteSpace) => siteSpace.space.id === spaceItem.id);
return { type: 'context' as const, results: [result] };
}
const isCurrentRevisionSpace = Boolean(revision && resultItem.id === siteURLData.space);
const found =
isCurrentRevisionSpace && currentSiteSpace
? currentSiteSpace
: findSiteSpaceBy(
structure,
(siteSpace) => siteSpace.space.id === resultItem.id
);
return {
type: 'pages' as const,
results: resultItem.pages.flatMap((pageItem) => {
const result = transformSitePageResult({
asEmbeddable: Boolean(asEmbeddable),
linker: isCurrentRevisionSpace ? revisionLinker : context.linker,
pageItem,
spaceItem: resultItem,
siteSpace: found?.siteSpace,
siteSection: found?.siteSection ?? undefined,
siteSectionGroup: found?.siteSectionGroup ?? undefined,
revisionPages: isCurrentRevisionSpace ? revision?.pages : undefined,
});
return result ? [{ rank: pageItem.rank, result }] : [];
}),
};
})
);
return transformSitePageResult({
asEmbeddable: Boolean(asEmbeddable),
linker: isCurrentRevisionSpace ? revisionLinker : context.linker,
pageItem,
spaceItem,
siteSpace: found?.siteSpace,
siteSection: found?.siteSection ?? undefined,
siteSectionGroup: found?.siteSectionGroup ?? undefined,
revisionPages: isCurrentRevisionSpace ? revision?.pages : undefined,
});
});
return NextResponse.json(results);
}
+21 -2
View File
@@ -1,5 +1,6 @@
import { jwtDecode } from 'jwt-decode';
import { forbidden, notFound } from 'next/navigation';
import { cache } from 'react';
import rison from 'rison';
import type { SiteAPIToken } from '@gitbook/api';
@@ -27,7 +28,17 @@ export type RouteParams = RouteLayoutParams & {
/**
* Get the static context when rendering statically a site.
*/
export async function getStaticSiteContext(params: RouteLayoutParams) {
export function getStaticSiteContext(params: RouteLayoutParams) {
return getStaticSiteContextCached(params.mode, params.siteURL, params.siteData);
}
// Layouts, pages and their metadata functions each resolve the context: share it per request.
// Keyed on the raw strings as `params` objects aren't guaranteed to be the same reference.
const getStaticSiteContextCached = cache((mode: string, siteURL: string, siteData: string) =>
resolveStaticSiteContext({ mode, siteURL, siteData })
);
async function resolveStaticSiteContext(params: RouteLayoutParams) {
const siteURL = getSiteURLFromParams(params);
const siteURLData = getSiteURLDataFromParams(params);
@@ -57,7 +68,15 @@ export async function getStaticSiteContext(params: RouteLayoutParams) {
* Get the site context when rendering dynamically.
* The context will depend on the request.
*/
export async function getDynamicSiteContext(params: RouteLayoutParams) {
export function getDynamicSiteContext(params: RouteLayoutParams) {
return getDynamicSiteContextCached(params.mode, params.siteURL, params.siteData);
}
const getDynamicSiteContextCached = cache((mode: string, siteURL: string, siteData: string) =>
resolveDynamicSiteContext({ mode, siteURL, siteData })
);
async function resolveDynamicSiteContext(params: RouteLayoutParams) {
const siteURL = getSiteURLFromParams(params);
const siteURLData = getSiteURLDataFromParams(params);
@@ -65,7 +65,7 @@ export async function* streamAIChatResponse({
},
]
: [],
model: AIModel.ReasoningLow,
model: AIModel.ReasoningMedium,
previousResponseId,
toolCall,
tools,
@@ -57,7 +57,6 @@ export function CookiesToast(props: { privacyPolicy?: string }) {
<div
role="dialog"
data-testid="cookies-dialog"
aria-modal="true"
aria-label={tString(language, 'cookies_title')}
aria-describedby={describedById}
className={tcls(
@@ -180,7 +180,11 @@ function CodeBlockExpandable(props: {
<div
className={tcls(
!isExpanded
? '[&_pre]:h-[calc(2rem+var(--line-count)*var(--line-height))] [&_pre]:overflow-y-hidden'
? [
'[&_pre]:h-[calc(2rem+var(--line-count)*var(--line-height))] [&_pre]:overflow-y-hidden',
// Mask the code rather than the pre to keep its border, with stops on the visible lines.
'[&_code]:mask-b-from-[calc((var(--line-count)+1)*var(--line-height)*0.55)] [&_code]:mask-b-to-[calc((var(--line-count)+1)*var(--line-height))]',
]
: ''
)}
style={
@@ -127,8 +127,7 @@ export const CodeBlockRenderer = forwardRef(function CodeBlockRenderer(
<code
className={tcls(
'table max-h-full w-fit min-w-full [counter-reset:line] print:max-h-none print:whitespace-pre-wrap',
withWrap && 'whitespace-pre-wrap',
'[[aria-expanded=false]_&]:mask-b-from-50%'
withWrap && 'whitespace-pre-wrap'
)}
>
{theme.lines.map((line, index) => (
@@ -1,8 +1,7 @@
'use client';
import React from 'react';
import { getCodeTextFromId } from './utils';
import { useCopyToClipboard } from '@/components/hooks';
import { Button } from '@/components/primitives';
import { t, useLanguage } from '@/intl/client';
import { type ClassValue, tcls } from '@/lib/tailwind';
@@ -15,41 +14,30 @@ export function CopyCodeButton(props: { codeId: string; style: ClassValue }) {
const { codeId, style } = props;
const language = useLanguage();
const [copied, setCopied] = React.useState(false);
React.useEffect(() => {
if (!copied) {
return;
}
const timeout = setTimeout(() => {
setCopied(false);
}, 1000);
return () => {
clearTimeout(timeout);
};
}, [copied]);
const { copied, copy } = useCopyToClipboard();
const onClick = () => {
const codeText = getCodeTextFromId(codeId);
if (codeText === null) {
return;
}
navigator.clipboard.writeText(codeText);
setCopied(true);
copy(codeText);
};
return (
<Button
size="xsmall"
variant="secondary"
onClick={onClick}
className={tcls(style, 'translate-y-0!', 'print:hidden')}
>
{t(language, copied ? 'code_copied' : 'code_copy')}
</Button>
<>
<Button
size="xsmall"
variant="secondary"
onClick={onClick}
className={tcls(style, 'translate-y-0!', 'print:hidden')}
>
{t(language, copied ? 'code_copied' : 'code_copy')}
</Button>
{/* A label swap on the focused button isn't announced, the live region is. */}
<span role="status" className="sr-only">
{copied ? t(language, 'code_copied') : null}
</span>
</>
);
}
@@ -1,6 +1,6 @@
import type { DocumentBlockHint } from '@gitbook/api';
import { Icon, type IconName } from '@gitbook/icons';
import { validateIconName } from '@gitbook/icons/icons';
import { validateIconName } from '@gitbook/icons/validateIconName';
import { Block, type BlockProps } from './Block';
import { Blocks } from './Blocks';
@@ -40,7 +40,12 @@ export async function InlineLink(props: InlineProps<DocumentInlineLink>) {
return (
<NotFoundRefHoverCard context={context}>
{fallback ? (
<InlineLinkAnchor href={fallback.href} contentRef={inline.data.ref} isExternal>
<InlineLinkAnchor
href={fallback.href}
contentRef={inline.data.ref}
target={inline.data.target}
isExternal
>
{inlinesElement}
</InlineLinkAnchor>
) : (
@@ -53,6 +58,7 @@ export async function InlineLink(props: InlineProps<DocumentInlineLink>) {
<InlineLinkAnchor
href={resolved.href}
contentRef={resolved.resolvedRef ?? inline.data.ref}
target={inline.data.target}
isExternal={(resolved.resolvedRef ?? inline.data.ref).kind === 'url'}
>
{inlinesElement}
@@ -75,14 +81,16 @@ export async function InlineLink(props: InlineProps<DocumentInlineLink>) {
function InlineLinkAnchor(props: {
href: string;
contentRef: ContentRef;
target: DocumentInlineLink['data']['target'];
isExternal?: boolean;
children: React.ReactNode;
}) {
const { href, isExternal, contentRef, children } = props;
const { href, isExternal, contentRef, target, children } = props;
const isMailto = href.startsWith('mailto:');
return (
<StyledLink
href={href}
target={target ? `_${target}` : undefined}
insights={{
type: 'link_click',
link: {
@@ -129,7 +129,7 @@
.contentkit-modal {
@apply flex flex-col gap-6 relative z-50 bg-tint
rounded shadow-lg opacity-0 transition-opacity duration-300 border border-tint
w-full max-w-[768px] max-h-[90vh] overflow-y-auto;
w-full max-w-[768px] max-h-[90dvh] overflow-y-auto;
}
.contentkit-modal.contentkit-modal-opened {
@apply opacity-[1];
@@ -16,6 +16,8 @@ import { matchesText } from '../Table/searchMatch';
import { MIN_RECORDS_FOR_SEARCH } from '../Table/shouldShowSearch';
import { Input } from '@/components/primitives';
import { tString, useLanguage } from '@/intl/client';
// Imported here, behind the `next/dynamic` boundary, so only pages with OpenAPI blocks load it.
import './style.css';
// Only what survives the RSC boundary. Rebuilding the renderers on the client is what lets this
// whole subtree sit behind a `next/dynamic` chunk instead of the route's eager entry.
@@ -17,7 +17,6 @@ import { PlainCodeBlock } from '../CodeBlock';
import { DocumentView } from '../DocumentView';
import { Heading } from '../Heading';
import type { OpenAPIBlockClientContextProps } from './OpenAPIBlockClient';
import './style.css';
import { SCALAR_RUNTIME_PATH } from './scalar-runtime-path';
import { DEFAULT_LOCALE, getSpaceLocale } from '@/intl/server';
import { getAssetURL } from '@/lib/assets';
@@ -0,0 +1,46 @@
/* Global, not in style.css: badges also show in the sidebar and outline of pages without OpenAPI blocks. */
.openapi-method,
.openapi-statuscode {
@apply m-0 h-5 min-w-9 justify-center rounded-md text-xs straight-corners:rounded-none circular-corners:rounded-lg uppercase font-mono items-center shrink-0 font-semibold px-1.5 py-0.5 text-tint-12/8 leading-tight align-middle inline-flex whitespace-nowrap;
}
.openapi-method-small {}
.openapi-method-medium {
@apply m-0 px-2.5 py-1 h-6 text-[0.813rem];
}
.toclink .openapi-method {
@apply text-[0.625rem] flex items-center justify-center;
}
.openapi-method-get,
.openapi-statuscode-success {
@apply bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-100;
}
.openapi-method-post,
.openapi-statuscode-redirection {
@apply bg-amber-100 text-amber-800 dark:bg-amber-900 dark:text-amber-100;
}
.openapi-method-put,
.openapi-statuscode-informational {
@apply bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-100;
}
.openapi-method-patch {
@apply bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-100;
}
.openapi-method-delete,
.openapi-statuscode-error {
@apply bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-100;
}
.openapi-method-head,
.openapi-method-options,
.openapi-method-trace,
.openapi-method-hook {
@apply bg-tint;
}
@@ -143,53 +143,6 @@ button.openapi-mcp {
@apply !mb-0;
}
/* Method Tags */
.openapi-method,
.openapi-statuscode {
@apply m-0 h-5 min-w-9 justify-center rounded-md text-xs straight-corners:rounded-none circular-corners:rounded-lg uppercase font-mono items-center shrink-0 font-semibold px-1.5 py-0.5 text-tint-12/8 leading-tight align-middle inline-flex whitespace-nowrap;
}
.openapi-method-small {}
.openapi-method-medium {
@apply m-0 px-2.5 py-1 h-6 text-[0.813rem];
}
.toclink .openapi-method {
@apply text-[0.625rem] flex items-center justify-center;
}
.openapi-method-get,
.openapi-statuscode-success {
@apply bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-100;
}
.openapi-method-post,
.openapi-statuscode-redirection {
@apply bg-amber-100 text-amber-800 dark:bg-amber-900 dark:text-amber-100;
}
.openapi-method-put,
.openapi-statuscode-informational {
@apply bg-blue-100 text-blue-800 dark:bg-blue-900 dark:text-blue-100;
}
.openapi-method-patch {
@apply bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-100;
}
.openapi-method-delete,
.openapi-statuscode-error {
@apply bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-100;
}
.openapi-method-head,
.openapi-method-options,
.openapi-method-trace,
.openapi-method-hook {
@apply bg-tint;
}
/* URL */
.openapi-url {
@apply font-mono text-sm text-tint;
@@ -4,7 +4,7 @@ import {
type DocumentBlockPrompt,
type SiteCustomizationSettings,
} from '@gitbook/api';
import { validateIconName } from '@gitbook/icons/icons';
import { validateIconName } from '@gitbook/icons/validateIconName';
import type { BlockProps } from '../Block';
import { CodeBlock } from '../CodeBlock';
@@ -5,6 +5,7 @@ import React from 'react';
import { Icon } from '@gitbook/icons';
import { type PromptActionId, setPromptAction, usePromptAction } from './promptAction';
import { useCopyToClipboard } from '@/components/hooks';
import {
Button,
ButtonGroup,
@@ -27,25 +28,10 @@ export function PromptActions(props: { prompt: string; openInAIProviders: boolea
const { prompt, openInAIProviders } = props;
const language = useLanguage();
const selectedAction = usePromptAction();
const [copied, setCopied] = React.useState(false);
React.useEffect(() => {
if (!copied) {
return;
}
const timeout = setTimeout(() => {
setCopied(false);
}, COPIED_MESSAGE_DURATION);
return () => {
clearTimeout(timeout);
};
}, [copied]);
const { copied, copy } = useCopyToClipboard(COPIED_MESSAGE_DURATION);
const copyPrompt = () => {
navigator.clipboard.writeText(prompt);
setCopied(true);
copy(prompt);
};
// The pick follows the visitor from site to site, so fall back to copying wherever the agent
@@ -12,7 +12,13 @@ mock.module('./RecordCard', () => ({
}));
mock.module('./TableSearch', () => ({
TableSearchRecord: ({ children }: { children: React.ReactNode }) => <>{children}</>,
TableSearchRecord: ({
children,
visibleClassName,
}: {
children: React.ReactNode;
visibleClassName: string;
}) => <div className={visibleClassName}>{children}</div>,
}));
const { ViewCards } = await import('./ViewCards');
@@ -43,21 +49,51 @@ describe('ViewCards', () => {
it('renders the carousel with a symmetric peek and conditional edge masks', () => {
const markup = renderWithContext(<ViewCards {...makeProps(false)} />);
expect(markup).toContain('-mx-12');
expect(markup).toContain('px-12');
expect(markup).toContain('scroll-px-12');
// Gutter-sized peek, the full 3rem from `2xl`.
expect(markup).toContain('-mx-4 sm:-mx-6 md:-mx-8 2xl:-mx-12');
expect(markup).toContain('scroll-px-4');
expect(markup).toContain('2xl:scroll-px-12');
expect(markup).toContain('left-0');
expect(markup).toContain('ml-8');
expect(markup).toContain('2xl:ml-8');
expect(markup).toContain('right-0');
expect(markup).toContain('mr-8');
expect(markup).toContain('2xl:mr-8');
expect(markup).not.toContain('before:bg-linear-to-r');
expect(markup).not.toContain('after:bg-linear-to-l');
expect(markup).toContain('snap-mandatory');
});
it('renders the wrapping grid by default', () => {
const markup = renderWithContext(<ViewCards {...makeProps(true)} />);
it.each([true, undefined])('renders the wrapping grid with wrap=%s', (wrap) => {
const props = makeProps(true);
props.view.wrap = wrap;
const markup = renderWithContext(<ViewCards {...props} />);
expect(markup).toContain('inline-grid');
});
it('renders small cards in four columns and uses the grid for print', () => {
const props = makeProps(true);
props.view.cardSize = 'small';
expect(renderWithContext(<ViewCards {...props} />)).toContain('@3xl:grid-cols-4');
props.view.wrap = false;
const carousel = renderWithContext(<ViewCards {...props} />);
expect(carousel).toContain('@3xl:w-[calc(22.5%-0.75rem)]');
expect(carousel).toContain('@5xl:w-[calc(25%-0.75rem)]');
props.context.mode = 'print';
const printed = renderWithContext(<ViewCards {...props} />);
expect(printed).toContain('@3xl:grid-cols-4');
expect(printed).not.toContain('snap-mandatory');
});
it.each([
['medium', '@2xl:grid-cols-3 @sm:grid-cols-2', '@5xl:w-[calc(33.33%-0.66rem)]'],
['large', '@xl:grid-cols-2', '@5xl:w-[calc(50%-0.5rem)]'],
['unknown', '@2xl:grid-cols-3 @sm:grid-cols-2', '@5xl:w-[calc(33.33%-0.66rem)]'],
])('preserves %s card layouts', (cardSize, grid, carousel) => {
const props = makeProps(true);
props.view.cardSize = cardSize;
expect(renderWithContext(<ViewCards {...props} />)).toContain(grid);
props.view.wrap = false;
expect(renderWithContext(<ViewCards {...props} />)).toContain(carousel);
});
});
@@ -6,6 +6,18 @@ import { TableSearchRecord } from './TableSearch';
import { ScrollContainer } from '@/components/primitives/ScrollContainer';
import { tcls } from '@/lib/tailwind';
const gridColumns = {
small: '@sm:grid-cols-2 @2xl:grid-cols-3 @3xl:grid-cols-4',
medium: '@2xl:grid-cols-3 @sm:grid-cols-2',
large: '@xl:grid-cols-2',
};
const carouselWidths = {
small: 'w-[90%] @sm:w-[calc(45%-0.5rem)] @xl:w-[calc(30%-0.66rem)] @3xl:w-[calc(22.5%-0.75rem)] @5xl:w-[calc(25%-0.75rem)]',
medium: 'w-[90%] @sm:w-[calc(45%-0.5rem)] @xl:w-[calc(30%-0.66rem)] @5xl:w-[calc(33.33%-0.66rem)]',
large: 'w-[90%] @sm:w-[calc(45%-0.5rem)] @5xl:w-[calc(50%-0.5rem)]',
};
export function ViewCards(props: TableViewProps<DocumentTableViewCards>) {
// `wrap` defaults to `true` (a wrapping grid); only an explicit `false` opts into the
// horizontally-scrolling carousel row. Fall back to the grid in print mode: a PDF can't
@@ -30,7 +42,7 @@ function CardsGrid(props: TableViewProps<DocumentTableViewCards>) {
'inline-grid',
'gap-4',
'grid-cols-1',
view.cardSize === 'large' ? '@xl:grid-cols-2' : '@2xl:grid-cols-3 @sm:grid-cols-2', // Large cards break earlier to avoid becoming *too* big.
gridColumns[view.cardSize] ?? gridColumns.medium,
block.data.fullWidth ? 'large:flex-column' : null
)}
>
@@ -49,6 +61,16 @@ function CardsGrid(props: TableViewProps<DocumentTableViewCards>) {
);
}
// The peek fits the page gutter (`CONTAINER_STYLE`) so the fade stays on screen; from `2xl` the
// cards fill the row exactly and need the full 3rem to show the next one.
const PEEK = {
margin: '-mx-4 sm:-mx-6 md:-mx-8 2xl:-mx-12',
padding:
'px-4 scroll-px-4 sm:px-6 sm:scroll-px-6 md:px-8 md:scroll-px-8 2xl:px-12 2xl:scroll-px-12',
leadingButton: 'ml-0 sm:ml-2 md:ml-4 2xl:ml-8',
trailingButton: 'mr-0 sm:mr-2 md:mr-4 2xl:mr-8',
};
/**
* The carousel layout: cards lay out in a single horizontally-scrolling row that
* snaps to the leftmost card. Reuses ScrollContainer for the scroll buttons.
@@ -60,17 +82,10 @@ function CardsGrid(props: TableViewProps<DocumentTableViewCards>) {
function CardsCarousel(props: TableViewProps<DocumentTableViewCards>) {
const { view, records } = props;
// Cards need a fixed width so the row overflows and scrolls; mirror the grid's
// medium/large sizing.
const cardWidth =
view.cardSize === 'large'
? 'w-[90%] @sm:w-[calc(45%-0.5rem)] @5xl:w-[calc(50%-0.5rem)]'
: 'w-[90%] @sm:w-[calc(45%-0.5rem)] @xl:w-[calc(30%-0.66rem)] @5xl:w-[calc(33.33%-0.66rem)]';
return (
<ScrollContainer
orientation="horizontal"
className={tcls('-mx-12', 'hover:z-11')}
className={tcls(PEEK.margin, 'hover:z-11')}
// `py-1` keeps the card ring/shadow from being clipped by the scroll overflow;
// `snap-mandatory` + the scroll-padding snap each card to the content edge.
contentClassName={tcls(
@@ -79,19 +94,18 @@ function CardsCarousel(props: TableViewProps<DocumentTableViewCards>) {
'-mt-px',
'pb-6',
'-mb-6',
'px-12',
'scroll-px-12',
PEEK.padding,
'snap-x',
'snap-mandatory'
)}
scrollByVisibleItems
leading={{
fade: true,
button: { size: 'small', className: 'ml-8' },
button: { size: 'small', className: PEEK.leadingButton },
}}
trailing={{
fade: true,
button: { size: 'small', className: 'mr-8' },
button: { size: 'small', className: PEEK.trailingButton },
}}
>
{records.map((record) => {
@@ -106,7 +120,7 @@ function CardsCarousel(props: TableViewProps<DocumentTableViewCards>) {
'grid-cols-1',
'shrink-0',
'snap-start',
cardWidth
carouselWidths[view.cardSize] ?? carouselWidths.medium
)}
>
<RecordCard {...props} record={record} />
@@ -0,0 +1,26 @@
import { describe, expect, it } from 'bun:test';
import { getNextTabIndex } from './DynamicTabs';
describe('getNextTabIndex', () => {
it('moves with the arrow keys and wraps around', () => {
expect(getNextTabIndex('ArrowRight', 0, 3)).toBe(1);
expect(getNextTabIndex('ArrowRight', 2, 3)).toBe(0);
expect(getNextTabIndex('ArrowLeft', 0, 3)).toBe(2);
});
it('jumps to the first and last tab', () => {
expect(getNextTabIndex('Home', 2, 3)).toBe(0);
expect(getNextTabIndex('End', 0, 3)).toBe(2);
});
it('mirrors the arrows in right-to-left', () => {
expect(getNextTabIndex('ArrowLeft', 0, 3, true)).toBe(1);
expect(getNextTabIndex('ArrowRight', 0, 3, true)).toBe(2);
});
it('ignores other keys and an unknown tab', () => {
expect(getNextTabIndex('Enter', 0, 3)).toBeNull();
expect(getNextTabIndex('ArrowRight', -1, 3)).toBeNull();
});
});
@@ -151,10 +151,15 @@ const TabItemList = memo(function TabItemList(props: {
}).filter((x) => x !== undefined),
[overflowing, tabs]
);
// Roving tabindex: one tab stop for the strip, the active tab when it isn't in the overflow menu.
const visibleTabs = tabs.filter((tab) => !overflowing.has(getTabButtonId(tab.id)));
const focusableTabId =
visibleTabs.find((tab) => tab.id === activeTabId)?.id ?? visibleTabs[0]?.id ?? null;
return (
<div
ref={containerRef}
role="tablist"
onKeyDown={moveFocusBetweenTabs}
className={tcls(
'group/tabs',
'overflow-hidden',
@@ -182,6 +187,7 @@ const TabItemList = memo(function TabItemList(props: {
key={tab.id}
ref={itemRef}
isActive={tab.id === activeTabId}
isFocusable={tab.id === focusableTabId}
isMeasuring={isMeasuring}
tab={tab}
onSelect={onSelect}
@@ -241,16 +247,18 @@ function TabsDropdownMenu(props: {
const TabItem = memo(function TabItem(props: {
ref: React.Ref<HTMLButtonElement>;
isActive: boolean;
isFocusable: boolean;
isMeasuring: boolean;
tab: TabsItem;
onSelect: (tabId: string) => void;
}) {
const { ref, tab, isActive, isMeasuring, onSelect } = props;
const { ref, tab, isActive, isFocusable, isMeasuring, onSelect } = props;
return (
<TabButton
ref={ref}
role="tab"
aria-selected={isActive}
tabIndex={isFocusable ? 0 : -1}
aria-controls={tab.id}
id={getTabButtonId(tab.id)}
title={tab.title}
@@ -343,6 +351,55 @@ function TabButton(
);
}
/**
* Arrow keys, Home and End move focus between the tabs of a tablist; Enter or Space then selects.
*/
function moveFocusBetweenTabs(event: React.KeyboardEvent<HTMLElement>) {
const current = event.target instanceof HTMLElement ? event.target : null;
if (current?.getAttribute('role') !== 'tab') {
return;
}
const tabs = Array.from(
event.currentTarget.querySelectorAll<HTMLElement>('[role="tab"]:not([disabled])')
);
const index = tabs.indexOf(current);
const isRTL = getComputedStyle(event.currentTarget).direction === 'rtl';
const next = getNextTabIndex(event.key, index, tabs.length, isRTL);
if (next === null) {
return;
}
event.preventDefault();
tabs[next]?.focus();
}
/**
* Index of the tab to focus for a key press, or null when the key doesn't move focus.
*/
export function getNextTabIndex(
key: string,
index: number,
count: number,
isRTL = false
): number | null {
if (index < 0 || count === 0) {
return null;
}
const forward = isRTL ? 'ArrowLeft' : 'ArrowRight';
const backward = isRTL ? 'ArrowRight' : 'ArrowLeft';
switch (key) {
case forward:
return (index + 1) % count;
case backward:
return (index - 1 + count) % count;
case 'Home':
return 0;
case 'End':
return count - 1;
default:
return null;
}
}
/**
* Get the ID for a tab button.
*/
@@ -1,6 +1,6 @@
import type { DocumentBlockTabs } from '@gitbook/api';
import type { IconName } from '@gitbook/icons';
import { validateIconName } from '@gitbook/icons/icons';
import { validateIconName } from '@gitbook/icons/validateIconName';
import type { BlockProps } from '../Block';
import { Blocks } from '../Blocks';
@@ -125,6 +125,9 @@ function Color(props: MarkedLeafProps<DocumentMarkColor>) {
const { mark, children } = props;
return (
<span
data-highlight={
mark.data.background && mark.data.background !== 'default' ? '' : undefined
}
className={tcls([
textColorToStyle[mark.data.text ?? 'default'],
backgroundColorToStyle[mark.data.background ?? 'default'],
@@ -5,7 +5,11 @@ import React, { useEffect, useRef } from 'react';
import { createStore, useStore } from 'zustand';
import type { GitBookIntegrationTool } from '@gitbook/browser-types';
import type { GitBookEmbeddableConfiguration, ParentToFrameMessage } from '@gitbook/embed';
import type {
FrameToParentMessage,
GitBookEmbeddableConfiguration,
ParentToFrameMessage,
} from '@gitbook/embed';
import { integrationsAssistantTools } from '../Integrations';
import { Button, LinkContext, type LinkContextType } from '../primitives';
@@ -69,6 +73,27 @@ export function EmbeddableIframeAPI(props: { baseURL: string }) {
});
}, [chatController]);
React.useEffect(() => {
const channel = getChannel();
if (!channel) {
return;
}
// Menus, dialogs and the zoomed image call preventDefault when Escape closes them.
const onKeyDown = (event: KeyboardEvent) => {
if (
event.key === 'Escape' &&
!event.defaultPrevented &&
!event.isComposing &&
!event.repeat
) {
channel.send({ type: 'escape' } satisfies FrameToParentMessage);
}
};
window.addEventListener('keydown', onKeyDown);
return () => window.removeEventListener('keydown', onKeyDown);
}, []);
React.useEffect(() => {
const channel = getChannel();
if (!channel) {
@@ -12,6 +12,7 @@ import { EmbeddableIframeAPI } from './EmbeddableIframeAPI';
import { EmbeddableThemeSync } from './EmbeddableThemeSync';
import { IfEmbeddableTrademark } from './EmbeddableTrademark';
import { CustomizationRootLayout } from '@/components/RootLayout';
import { getDirectSearchProps } from '@/components/Search/search-props';
import {
SiteLayoutClientContexts,
generateSiteLayoutMetadata,
@@ -60,6 +61,7 @@ export async function EmbeddableRootLayout({
contextId={context.contextId}
proxyOrigin={context.site.proxy?.origin}
searchPrewarmURL={context.linker.toPathInSite('~gitbook/search-prewarm')}
directSearch={getDirectSearchProps(context)}
>
{/* Persist an explicit ?theme= override so it survives tab navigation. RND-11571 */}
<EmbeddableThemeSync forcedTheme={rememberedTheme} />
@@ -50,7 +50,9 @@ export function EmbeddableSearch(props: EmbeddableSearchProps) {
error,
fetching,
onInputKeyDown,
inputHandlers,
onResultSelect,
onResultHover,
query,
results,
resultsId,
@@ -79,6 +81,7 @@ export function EmbeddableSearch(props: EmbeddableSearchProps) {
resultsId={resultsId}
resultsRef={resultsRef}
onResultSelect={onResultSelect}
onResultHover={onResultHover}
showAsk={showAsk}
dataTestId="embed-search"
input={
@@ -89,6 +92,7 @@ export function EmbeddableSearch(props: EmbeddableSearchProps) {
aria-controls={resultsId}
onChange={setQuery}
onKeyDown={onInputKeyDown}
{...inputHandlers}
value={searchValue}
withAI={withSearchAI}
isOpen={true}
@@ -0,0 +1,25 @@
import { describe, expect, it } from 'bun:test';
import { isForeignHandshake } from './channel';
describe('isForeignHandshake', () => {
const parent = {} as MessageEventSource;
const other = {} as MessageEventSource;
it('accepts a handshake from the expected window', () => {
expect(isForeignHandshake({ data: { type: 'bidc-connect' }, source: parent }, parent)).toBe(
false
);
});
it('rejects a handshake from another window', () => {
expect(isForeignHandshake({ data: { type: 'bidc-connect' }, source: other }, parent)).toBe(
true
);
});
it('ignores messages that are not handshakes', () => {
expect(isForeignHandshake({ data: { type: 'other' }, source: other }, parent)).toBe(false);
expect(isForeignHandshake({ data: null, source: other }, parent)).toBe(false);
});
});
@@ -9,11 +9,33 @@ export function log(...data: any[]) {
console.log(...data);
}
/**
* Whether a message is a bidc handshake sent by a window other than the expected one.
*/
export function isForeignHandshake(
event: Pick<MessageEvent, 'data' | 'source'>,
expectedSource: MessageEventSource
): boolean {
return event.data?.type === 'bidc-connect' && event.source !== expectedSource;
}
export const getChannel = memoize(() => {
if (typeof window === 'undefined' || window.parent === window) {
return null;
}
log('[gitbook] create channel with parent window');
// bidc accepts a handshake from any window; registered first and in capture so it runs before
// bidc's own listener and only the embedding page can open the channel.
window.addEventListener(
'message',
(event) => {
if (isForeignHandshake(event, window.parent)) {
event.stopImmediatePropagation();
}
},
true
);
return createChannel();
});
@@ -55,6 +55,8 @@ export async function Header(props: {
'flex-none',
'shadow-[0px_1px_0px]',
'shadow-tint-12/2',
// Box shadows are dropped in forced colors mode, the separator needs a real border.
'forced-colors:border-b',
'bg-tint-base/9',
'theme-muted:bg-tint-subtle/9',
@@ -9,7 +9,7 @@ interface HeaderLinksProps {
export async function HeaderLinks({ children, style }: HeaderLinksProps) {
return (
<div
<nav
className={tcls(
'header-links',
'@4xl:[&>.button+.button]:-ml-2 z-20 ml-auto flex min-w-9 shrink grow @7xl:grow-0 items-center justify-end @4xl:gap-x-6 gap-x-4',
@@ -17,6 +17,6 @@ export async function HeaderLinks({ children, style }: HeaderLinksProps) {
)}
>
{children}
</div>
</nav>
);
}
@@ -193,13 +193,18 @@ export function InsightsProvider(props: InsightsProviderProps) {
}
);
/**
* When the page is unloaded, flush all events.
*/
// `beforeunload` doesn't fire reliably on mobile, hiding the page is the last dependable signal.
React.useEffect(() => {
window.addEventListener('beforeunload', flushEventsSync);
const flushWhenHidden = () => {
if (document.visibilityState === 'hidden') {
flushEventsSync();
}
};
document.addEventListener('visibilitychange', flushWhenHidden);
window.addEventListener('pagehide', flushEventsSync);
return () => {
window.removeEventListener('beforeunload', flushEventsSync);
document.removeEventListener('visibilitychange', flushWhenHidden);
window.removeEventListener('pagehide', flushEventsSync);
};
}, [flushEventsSync]);
@@ -73,7 +73,11 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
'mt-2',
'first:mt-0',
'mb-0.5',
section.depth > 1 && ['ml-3', 'my-0', 'sidebar-list-line:ml-0']
section.depth > 1 && [
section.depth > 2 ? 'ml-6' : 'ml-3',
'my-0',
'sidebar-list-line:ml-0',
]
)}
ref={activeId === section.id ? activeItemRef : null}
{...(section.tags !== undefined
@@ -82,6 +86,7 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
>
<a
href={`#${section.id}`}
aria-current={activeId === section.id ? 'true' : undefined}
data-cover-aware-text
className={tcls(
'relative',
@@ -118,7 +123,9 @@ export function ScrollSectionsList({ sections }: { sections: DocumentSection[] }
section.depth > 1 && [
'subitem',
'sidebar-list-line:pl-6',
section.depth > 2
? 'sidebar-list-line:pl-9'
: 'sidebar-list-line:pl-6',
'opacity-8',
'contrast-more:opacity-11',
@@ -16,6 +16,7 @@ import { PageCover } from './PageCover';
import { PageFooterNavigation } from './PageFooterNavigation';
import { PageHeader } from './PageHeader';
import { PreservePageLayout } from './PreservePageLayout';
import { MAIN_CONTENT_ID } from '@/components/layout';
import { getSpaceLanguage } from '@/intl/server';
import { t } from '@/intl/translate';
import type { GitBookSiteContext } from '@/lib/context';
@@ -26,7 +27,6 @@ import {
hasTopLevelBlock,
isNodeEmpty,
} from '@/lib/document';
import { getLLMsTxtURL, getPageMarkdownURL } from '@/lib/llms-directive';
import type { AncestorRevisionPage } from '@/lib/pages';
import { tcls } from '@/lib/tailwind';
import { getPageRSSURL } from '@/routes/rss';
@@ -103,6 +103,7 @@ export async function PageBody(props: {
/>
) : null}
<main
id={MAIN_CONTENT_ID}
// Comments on the whole page target anywhere in it that isn't a block.
{...(withCommentAnchors ? { 'data-comment-page': '' } : {})}
className={tcls(
@@ -120,7 +121,6 @@ export async function PageBody(props: {
)}
>
<PreservePageLayout wideLayout={wideLayout} pageHasToc={pageHasToc} />
<LLMsTxtPageDirective context={context} page={page} />
{page.cover && page.layout.cover && page.layout.coverSize === 'hero' ? (
<PageCover as="hero" page={page} cover={page.cover} context={context} />
) : null}
@@ -205,14 +205,3 @@ export async function PageBody(props: {
</CurrentPageProvider>
);
}
function LLMsTxtPageDirective(props: { context: GitBookSiteContext; page: RevisionPageDocument }) {
const { context, page } = props;
return (
<div className="sr-only">
For the complete documentation index, see <a href={getLLMsTxtURL(context)}>llms.txt</a>.
This page is also available as <a href={getPageMarkdownURL(context, page)}>Markdown</a>.
</div>
);
}
@@ -1,7 +1,11 @@
import type { StaticImageData } from 'next/image';
import { assert } from 'ts-essentials';
import type { RevisionPageDocument, RevisionPageDocumentCover } from '@gitbook/api';
import {
CustomizationDefaultThemeMode,
type RevisionPageDocument,
type RevisionPageDocumentCover,
} from '@gitbook/api';
import { CONTENT_STYLE } from '../layout';
import { getCoverHeight } from './coverHeight';
@@ -144,6 +148,11 @@ export async function PageCover(props: {
y={cover.yPos}
height={height}
mask={mask}
priorityTheme={
context.customization.themes.default === CustomizationDefaultThemeMode.Dark
? 'dark'
: 'light'
}
/>
</div>
</>
@@ -25,10 +25,14 @@ interface PageCoverImageProps {
// Only if the `height` was customized by the user (and thus defined), we use it to set the cover's height and skip the default behaviour of fixed aspect-ratio.
height: number | undefined;
mask?: 'none' | 'radial';
/** Theme most visitors see first, its cover is the LCP candidate. */
priorityTheme?: 'light' | 'dark';
}
export function PageCoverImage(props: PageCoverImageProps) {
const { imgs, y, height, mask } = props;
const { imgs, y, height, mask, priorityTheme = 'light' } = props;
// The light cover is never demoted to low: a visitor can still have switched to the light theme.
const darkFirst = priorityTheme === 'dark' && Boolean(imgs.dark);
const { objectPositionY, isLoading } = useCoverPosition(imgs, y, {
height,
aspectRatio: PAGE_COVER_SIZE,
@@ -48,7 +52,7 @@ export function PageCoverImage(props: PageCoverImageProps) {
src={imgs.light.src}
srcSet={imgs.light.srcSet}
sizes={imgs.light.sizes}
fetchPriority="high"
fetchPriority={darkFirst ? 'auto' : 'high'}
alt="Page cover"
className={tcls('w-full', 'object-cover', imgs.dark ? 'dark:hidden' : '')}
style={{
@@ -69,7 +73,7 @@ export function PageCoverImage(props: PageCoverImageProps) {
src={imgs.dark.src}
srcSet={imgs.dark.srcSet}
sizes={imgs.dark.sizes}
fetchPriority="low"
fetchPriority={darkFirst ? 'high' : 'low'}
alt="Page cover"
className={tcls('w-full', 'object-cover', 'dark:inline', 'hidden')}
style={{
@@ -56,7 +56,6 @@ function preloadFont(fontData: FontData) {
ReactDOM.preload(url, {
as: 'font',
crossOrigin: 'anonymous',
fetchPriority: 'high',
type: format ? `font/${format}` : undefined,
});
});
@@ -3,6 +3,7 @@
@config '../../../tailwind.config.ts';
@import "./prose.css";
@import "../DocumentView/OpenAPI/method-badge.css";
/*
The default border color has changed to `currentcolor` in Tailwind CSS v4,
@@ -33,7 +34,6 @@
@utility hide-scrollbar {
/* Hide scrollbar by default */
scrollbar-color: transparent transparent;
transition: scrollbar-color 0.2s ease-in-out;
&:hover {
/* Show scrollbar on hover */
@@ -52,21 +52,14 @@
rgba(0, 0, 0, 1) 96px,
rgba(0, 0, 0, 0)
);
mask-image: linear-gradient(
to bottom,
rgba(0, 0, 0, 1) 96px,
rgba(0, 0, 0, 0)
);
}
@utility linear-mask-util {
mask-image: linear-gradient(to bottom, white, white);
mask-image: linear-gradient(to bottom, white, white);
}
@utility grid-area-1-1 {
grid-area: 1 / 1;
grid-area: 1 / 1;
}
@utility gutter-stable {
@@ -102,41 +95,6 @@
border-top-right-radius: 30%;
}
&:before {
transform: rotate(-135deg) skewX(-45deg) scale(1.414, 0.707)
translate(0, -50%);
}
&:after {
transform: rotate(135deg) skewY(-45deg) scale(0.707, 1.414) translate(50%);
}
position: relative;
background-color: orange;
text-align: left;
transform: rotate(-60deg) skewX(-30deg) scale(1, 0.866);
&:before {
content: "";
position: absolute;
background-color: inherit;
}
&:after {
content: "";
position: absolute;
background-color: inherit;
}
width: inherit;
height: inherit;
border-top-right-radius: 30%;
&:before {
width: inherit;
height: inherit;
border-top-right-radius: 30%;
}
&:after {
width: inherit;
height: inherit;
border-top-right-radius: 30%;
}
&:before {
transform: rotate(-135deg) skewX(-45deg) scale(1.414, 0.707)
translate(0, -50%);
@@ -152,21 +110,14 @@
word-break: break-word;
overflow-wrap: anywhere;
}
word-break: break-word;
@supports (overflow-wrap: anywhere) {
word-break: break-word;
overflow-wrap: anywhere;
}
}
@utility bg-gradient-primary {
@apply bg-linear-to-bl from-primary-4 to-tint-base to-60% bg-fixed;
@apply bg-linear-to-bl from-primary-4 to-tint-base to-60% bg-fixed;
}
@utility bg-gradient-tint {
@apply bg-linear-to-bl from-tint-4 to-tint-base to-60% bg-fixed;
@apply bg-linear-to-bl from-tint-4 to-tint-base to-60% bg-fixed;
}
@utility site-background {
@@ -186,24 +137,6 @@
}
}
/*
The default border color has changed to `currentcolor` in Tailwind CSS v4,
so we've added these compatibility styles to make sure everything still
looks the same as it did with Tailwind CSS v3.
If we ever want to remove these styles, we need to add an explicit border
color utility to any element that depends on these defaults.
*/
@layer base {
*,
::after,
::before,
::backdrop,
::file-selector-button {
border-color: var(--color-gray-200, currentcolor);
}
}
@layer base {
:root {
@apply leading-relaxed;
@@ -575,6 +508,18 @@ html.dark .highlight-line.diff-deleted .highlight-line-content::before {
@apply text-contrast-cover;
}
}
/*
Inline code and highlights sit on their own background, not the cover, so they keep the regular
text color. Inherited, the transparent fill of a split element hides their text behind that
background. Kept out of the utilities layer so a highlight's own text color still applies.
*/
@media not (prefers-contrast: more) {
[data-over-cover] :is(code, [data-highlight]) {
color: var(--cover-text-below);
-webkit-text-fill-color: currentcolor;
}
}
}
/* Zoomable images */
@@ -680,3 +625,275 @@ html:has(.zoom-modal) {
}
}
}
/* Enter and exit animations, referenced by the `animation` theme in tailwind.config.ts. */
@keyframes present {
from {
opacity: 0;
transform: translateY(1rem) scale(90%);
}
to {
opacity: 1;
transform: translateY(0) scale(1);
}
}
@keyframes scaleIn {
from {
opacity: 0;
transform: rotateX(-10deg) scale(0.9);
}
to {
opacity: 1;
transform: rotateX(0deg) scale(1);
}
}
@keyframes scaleOut {
from {
opacity: 1;
transform: rotateX(0deg) scale(1);
}
to {
opacity: 0;
transform: rotateX(-10deg) scale(0.95);
}
}
@keyframes blurIn {
0% {
filter: blur(6px);
opacity: 0;
transform: scale(0.95);
}
100% {
filter: blur(0px);
opacity: 1;
transform: scale(1);
}
}
@keyframes blurOut {
0% {
filter: blur(0px);
opacity: 1;
transform: scale(1);
}
100% {
filter: blur(6px);
opacity: 0;
transform: scale(0.95);
}
}
@keyframes blurInDisplay {
0% {
filter: blur(6px);
opacity: 0;
transform: scale(0.95);
display: none;
}
100% {
filter: blur(0px);
opacity: 1;
transform: scale(1);
}
}
@keyframes blurOutDisplay {
0% {
filter: blur(0px);
opacity: 1;
transform: scale(1);
}
to {
filter: blur(6px);
opacity: 0;
transform: scale(0.95);
display: none;
}
}
@keyframes enterFromLeft {
from {
opacity: 0;
transform: translateX(-50%);
display: none;
}
to {
opacity: 1;
transform: translateX(0);
display: flex;
}
}
@keyframes enterFromRight {
from {
opacity: 0;
transform: translateX(50%);
display: none;
}
to {
opacity: 1;
transform: translateX(0);
display: flex;
}
}
@keyframes exitToLeft {
from {
opacity: 1;
transform: translateX(0);
display: flex;
}
to {
opacity: 0;
transform: translateX(-50%);
display: none;
}
}
@keyframes exitToRight {
from {
opacity: 1;
transform: translateX(0);
display: flex;
}
to {
opacity: 0;
transform: translateX(50%);
display: none;
}
}
/*
* Reduced motion keeps the fades and drops the movement. Redefining the keyframes rather than
* disabling the animations keeps their duration, so code waiting on `animationend` is unaffected.
* Each variant keeps the identity transform and filter of the full animation's end state: with
* `fill-mode: both` they persist, and dropping them would change stacking and text rasterization.
*/
@media (prefers-reduced-motion: reduce) {
@keyframes present {
from {
opacity: 0;
transform: translateY(0) scale(1);
}
to {
opacity: 1;
transform: translateY(0) scale(1);
}
}
@keyframes scaleIn {
from {
opacity: 0;
transform: rotateX(0deg) scale(1);
}
to {
opacity: 1;
transform: rotateX(0deg) scale(1);
}
}
@keyframes scaleOut {
from {
opacity: 1;
transform: rotateX(0deg) scale(1);
}
to {
opacity: 0;
transform: rotateX(0deg) scale(1);
}
}
@keyframes blurIn {
from {
filter: blur(0px);
opacity: 0;
transform: scale(1);
}
to {
filter: blur(0px);
opacity: 1;
transform: scale(1);
}
}
@keyframes blurOut {
from {
filter: blur(0px);
opacity: 1;
transform: scale(1);
}
to {
filter: blur(0px);
opacity: 0;
transform: scale(1);
}
}
@keyframes blurInDisplay {
from {
filter: blur(0px);
opacity: 0;
transform: scale(1);
display: none;
}
to {
filter: blur(0px);
opacity: 1;
transform: scale(1);
}
}
@keyframes blurOutDisplay {
from {
filter: blur(0px);
opacity: 1;
transform: scale(1);
}
to {
filter: blur(0px);
opacity: 0;
transform: scale(1);
display: none;
}
}
@keyframes enterFromLeft {
from {
opacity: 0;
transform: translateX(0);
display: none;
}
to {
opacity: 1;
transform: translateX(0);
display: flex;
}
}
@keyframes enterFromRight {
from {
opacity: 0;
transform: translateX(0);
display: none;
}
to {
opacity: 1;
transform: translateX(0);
display: flex;
}
}
@keyframes exitToLeft {
from {
opacity: 1;
transform: translateX(0);
display: flex;
}
to {
opacity: 0;
transform: translateX(0);
display: none;
}
}
@keyframes exitToRight {
from {
opacity: 1;
transform: translateX(0);
display: flex;
}
to {
opacity: 0;
transform: translateX(0);
display: none;
}
}
/* A loader must keep showing activity, so it slows down instead of stopping. */
.animate-spin {
animation-duration: 3s;
}
}
@@ -1,96 +0,0 @@
'use client';
import { Icon, type IconName } from '@gitbook/icons';
import { Emoji } from '../primitives/Emoji/Emoji';
import { Link } from '../primitives/Link';
import type { LocalPageResult } from './useLocalSearchResults';
import { tcls } from '@/lib/tailwind';
/**
* Renders local search results above the main server results.
*
* Layout:
* - While server results are still fetching → 2-column wrapping row (cards fill width)
* - Once server results are ready → single horizontal scrollable row (fixed-width cards)
*
* The card width is CSS-transitioned so the switch between the two layouts animates smoothly.
*/
export function LocalSearchResults({
results,
fetching,
}: {
results: LocalPageResult[];
fetching: boolean;
}) {
if (results.length === 0) return null;
return (
<div
className={tcls(
'py-2',
'flex',
'flex-row',
'gap-2',
fetching
? 'flex-wrap'
: ['overflow-x-auto', '[scrollbar-width:none]', '[&::-webkit-scrollbar]:hidden']
)}
>
{results.map((result) => (
<LocalSearchResultCard key={result.id} result={result} fetching={fetching} />
))}
</div>
);
}
function LocalSearchResultCard({
result,
fetching,
}: {
result: LocalPageResult;
fetching: boolean;
}) {
return (
<Link
href={result.pathname}
className={tcls(
'group',
'flex',
'flex-col',
'gap-1',
'p-3',
'rounded-corners:rounded-lg',
'circular-corners:rounded-2xl',
'text-tint',
'bg-tint-subtle',
'hover:bg-tint',
'hover:text-tint-strong',
'transition-colors',
'cursor-pointer',
fetching ? ['basis-[calc(50%-4px)]', 'min-w-0'] : ['w-40', 'shrink-0']
)}
>
<div className={tcls('flex', 'flex-row', 'items-center', 'gap-1.5', 'min-w-0')}>
{result.emoji ? (
<span className="size-4 shrink-0 text-tint-subtle">
<Emoji code={result.emoji} style="text-base leading-none" />
</span>
) : result.icon ? (
<span className="size-4 shrink-0 text-tint-subtle">
<Icon icon={result.icon as IconName} className="size-4" />
</span>
) : null}
<p className="grow truncate font-heading text-sm font-semibold leading-snug text-tint-strong">
{result.title}
</p>
<span className="ml-auto shrink-0 text-tint-subtle">
<Icon icon="chevron-right" className="size-3" />
</span>
</div>
{result.description ? (
<p className="line-clamp-2 text-xs leading-snug">{result.description}</p>
) : null}
</Link>
);
}
@@ -1,6 +1,5 @@
'use client';
import { KeyboardShortcut } from '../primitives/KeyboardShortcut';
import { addRecentSearchQuery } from './recent-queries';
import { SearchResultItem } from './SearchResultItem';
import { useSearchLink } from './useSearch';
@@ -16,10 +15,10 @@ export function SearchAskBar(props: {
query: string;
assistant: Assistant;
active?: boolean;
withShortcut?: boolean;
onHover?: () => void;
onSelect?: () => void;
}) {
const { query, assistant, active = false, withShortcut = false, onSelect } = props;
const { query, assistant, active = false, onHover, onSelect } = props;
const language = useLanguage();
const { siteSpaceId } = useCurrentContent();
const getSearchLinkProps = useSearchLink();
@@ -43,18 +42,14 @@ export function SearchAskBar(props: {
<SearchResultItem
{...linkProps}
active={active}
onHover={onHover}
action={tString(language, 'ask')}
leadingIcon={assistant.icon}
data-testid="search-ask-question"
className="gutter-stable rounded-none! shrink-0 overflow-y-scroll border-t border-tint-subtle pl-6 pr-5"
>
<div className="flex items-center justify-between gap-2">
<div className="line-clamp-1">
{t(language, 'ai_chat_ask_query', assistant.label, query)}
</div>
{withShortcut ? (
<KeyboardShortcut className="bg-tint-base" keys={['mod', 'i']} />
) : null}
<div className="line-clamp-1">
{t(language, 'ai_chat_ask_query', assistant.label, query)}
</div>
</SearchResultItem>
);
@@ -17,7 +17,7 @@ import { SearchLiveResultsAnnouncer } from './SearchLiveResultsAnnouncer';
import { SearchScopeControl } from './SearchScopeControl';
import { useSearchController } from './useSearchController';
import { useSearchPopupFocusTrap } from './useSearchPopupFocusTrap';
import { t, useLanguage } from '@/intl/client';
import { t, tString, useLanguage } from '@/intl/client';
import { tcls } from '@/lib/tailwind';
const SearchFrame = dynamic(() => import('./SearchFrame').then((mod) => mod.SearchFrame), {
@@ -43,6 +43,9 @@ export function SearchContainer({
const [searchPopup, setSearchPopup] = React.useState<HTMLDivElement | null>(null);
const language = useLanguage();
const usesSideSheet = useIsMobile(768);
// The header and sidebar copies are shown and hidden by CSS at the `lg` breakpoint.
const belowLg = useIsMobile();
const visible = viewport === 'desktop' ? !belowLg : viewport === 'mobile' ? belowLg : true;
const {
assistants,
askQuery,
@@ -53,7 +56,9 @@ export function SearchContainer({
error,
fetching,
onInputKeyDown,
inputHandlers,
onResultSelect,
onResultHover,
open,
query,
results,
@@ -66,7 +71,7 @@ export function SearchContainer({
withAI,
withSearchAI,
scopeControl,
} = useSearchController(searchProps);
} = useSearchController(searchProps, { requestsEnabled: visible });
const uiAssistants = assistants.filter((assistant) => assistant.ui === true);
useHotkeys(
@@ -114,8 +119,6 @@ export function SearchContainer({
};
}, [close]);
const visible =
viewport === 'desktop' ? !usesSideSheet : viewport === 'mobile' ? usesSideSheet : true;
const searchResultsActiveDescendant =
cursor !== null && cursor < results.length ? `${resultsId}-${cursor}` : undefined;
const isSearchOpen = Boolean(visible && (state?.open ?? false));
@@ -149,6 +152,7 @@ export function SearchContainer({
aria-controls={resultsId}
onChange={setQuery}
onKeyDown={onInputKeyDown}
{...inputHandlers}
value={searchValue}
withAI={withSearchAI}
isOpen={isSearchOpen}
@@ -176,6 +180,7 @@ export function SearchContainer({
resultsId={resultsId}
resultsRef={resultsRef}
onResultSelect={onResultSelect}
onResultHover={onResultHover}
showAsk={showAsk}
scopeControl={scopeControlNode}
fillHeight={usesSideSheet || shouldFillHeight}
@@ -203,6 +208,7 @@ export function SearchContainer({
active={isSearchOpen}
onClick={open}
className={className}
aria-label={tString(language, withSearchAI ? 'search_or_ask' : 'search')}
aria-expanded={isSearchOpen}
aria-controls={resultsId}
/>
@@ -214,6 +220,7 @@ export function SearchContainer({
aria-controls={resultsId}
onChange={setQuery}
onKeyDown={onInputKeyDown}
{...inputHandlers}
value={searchValue}
withAI={withSearchAI}
isOpen={isSearchOpen}
@@ -9,8 +9,6 @@ import {
EmbeddableFrameMain,
EmbeddableFrameSidebar,
} from '../Embeddable/EmbeddableFrame';
import { Tooltip } from '../primitives';
import { KeyboardShortcut } from '../primitives/KeyboardShortcut';
import { ScrollContainer } from '../primitives/ScrollContainer';
import { SearchAskAnswer } from './SearchAskAnswer';
import { SearchAskBar } from './SearchAskBar';
@@ -31,6 +29,8 @@ export function SearchFrame(props: {
resultsId: string;
resultsRef: React.Ref<SearchResultsRef>;
onResultSelect?: () => void;
/** Select the result under the mouse, so hover and keyboard share one highlight. */
onResultHover?: (index: number) => void;
scopeControl?: React.ReactNode;
showAsk: boolean;
sidebar?: React.ReactNode;
@@ -52,6 +52,7 @@ export function SearchFrame(props: {
resultsId,
resultsRef,
onResultSelect,
onResultHover,
scopeControl,
showAsk,
sidebar,
@@ -99,8 +100,16 @@ export function SearchFrame(props: {
<ScrollContainer
orientation="vertical"
className={tcls(fillHeight ? 'min-h-0 flex-1' : '')}
leading={{ fade: 'long', button: false }}
trailing={{
fade: 'long',
button: true,
// Loading placeholders are not more results.
buttonAlwaysVisible: results.length > 0,
}}
contentClassName={tcls(
'gutter-stable scroll-py-3 p-3',
// Keeps the keyboard selection clear of the faded edges.
'gutter-stable scroll-pt-12 scroll-pb-24 p-3',
fillHeight ? 'min-h-full' : ''
)}
>
@@ -116,6 +125,7 @@ export function SearchFrame(props: {
cursor={cursor}
error={error}
onResultSelect={onResultSelect}
onResultHover={onResultHover}
/>
)}
</ScrollContainer>
@@ -126,21 +136,16 @@ export function SearchFrame(props: {
query={query}
assistant={assistant}
active={cursor === results.length + index}
withShortcut={assistant === assistants[0]}
onHover={() => onResultHover?.(results.length + index)}
onSelect={onResultSelect}
/>
))
: null}
<div
className={tcls(
'flex gap-2 border-tint-subtle border-t bg-tint-subtle px-4 py-1.5',
!scopeControl ? 'not-pointer-fine:hidden' : '',
showAsk ? 'hidden' : ''
)}
>
{scopeControl && !showAsk ? scopeControl : null}
<SearchFrameKeyboardHints />
</div>
{scopeControl && !showAsk ? (
<div className="flex gap-2 border-t border-tint-subtle bg-tint-subtle px-4 py-1.5">
{scopeControl}
</div>
) : null}
</div>
</React.Suspense>
</EmbeddableFrameMain>
@@ -148,31 +153,3 @@ export function SearchFrame(props: {
</SearchAskProvider>
);
}
const SearchFrameKeyboardHints = () => {
return (
<div className="not-pointer-fine:hidden flex w-full items-center justify-end py-1.5 @container/keyboard-hint">
{/* Compact view */}
<div className="@max-[6rem]/keyboard-hint:hidden @min-[12rem]/keyboard-hint:hidden flex items-center gap-2">
<Tooltip label="Navigate">
<div>
<KeyboardShortcut className="bg-tint-base" keys={['up', 'down']} />
</div>
</Tooltip>
/
<Tooltip label="Close">
<div>
<KeyboardShortcut className="bg-tint-base" keys={['esc']} />
</div>
</Tooltip>
</div>
{/* Normal view */}
<div className="@max-[12rem]/keyboard-hint:hidden flex items-center gap-2">
<KeyboardShortcut className="bg-tint-base" keys={['up', 'down']} />
Navigate
<KeyboardShortcut className="ml-1 bg-tint-base" keys={['esc']} />
Close
</div>
</div>
);
};
@@ -13,6 +13,8 @@ interface SearchInputProps {
onChange: (value: string) => void;
onKeyDown: (event: React.KeyboardEvent<HTMLInputElement>) => void;
onFocus?: () => void;
onInput?: (event: React.FormEvent<HTMLInputElement>) => void;
onCompositionEnd?: (event: React.CompositionEvent<HTMLInputElement>) => void;
value: string;
withAI: boolean;
isOpen: boolean;
@@ -1,25 +1,20 @@
import React from 'react';
import { Icon, type IconName } from '@gitbook/icons';
import { Icon } from '@gitbook/icons';
import { SkeletonParagraph } from '../primitives';
import { useResizeObserver } from '../hooks';
import { Tooltip } from '../primitives';
import { Emoji } from '../primitives/Emoji/Emoji';
import { getPageResultPresentation } from './getPageResultHref';
import { HighlightQuery } from './HighlightQuery';
import type { MergedPageResult } from './reciprocalRankFusion';
import type { ComputedPageResult } from './search-types';
import { SearchResultItem } from './SearchResultItem';
import type { LocalPageResult } from './useLocalSearchResults';
import { tString, useLanguage } from '@/intl/client';
import { tcls } from '@/lib/tailwind';
type PageItem = ComputedPageResult | LocalPageResult | MergedPageResult;
export const SearchPageResultItem = React.forwardRef(function SearchPageResultItem(
props: {
query: string;
item: PageItem;
item: ComputedPageResult;
active: boolean;
style?: React.CSSProperties;
},
@@ -28,46 +23,19 @@ export const SearchPageResultItem = React.forwardRef(function SearchPageResultIt
const { query, item, active, style, ...rest } = props;
const language = useLanguage();
const { bestSection, description, href } = (() => {
if (item.type === 'page') {
const presentation = getPageResultPresentation(item);
return {
bestSection: presentation.preview,
description: presentation.description,
href: presentation.href,
};
}
return { bestSection: undefined, description: item.description, href: item.pathname };
})();
const { preview: bestSection, description, href } = getPageResultPresentation(item);
const preview = bestSection
? [bestSection.title, bestSection.body].filter(Boolean).join(' · ')
: undefined;
const emoji = 'emoji' in item ? item.emoji : undefined;
const icon = 'icon' in item ? item.icon : undefined;
const leadingIcon = emoji ? (
<span className="flex size-4 shrink-0 items-center justify-center">
<Emoji code={emoji} style="text-base leading-none" />
</span>
) : icon ? (
<Icon icon={icon as IconName} className="size-4" />
) : (
<Icon icon="file-lines" className="size-4" />
);
const insights =
item.type === 'page'
? {
type: 'search_open_result' as const,
query,
result: {
pageId: item.pageId,
spaceId: item.spaceId,
},
}
: undefined;
const insights = {
type: 'search_open_result' as const,
query,
result: {
pageId: item.pageId,
spaceId: item.spaceId,
},
};
return (
<SearchResultItem
@@ -76,7 +44,6 @@ export const SearchPageResultItem = React.forwardRef(function SearchPageResultIt
active={active}
data-testid="search-page-result"
action={tString(language, 'view')}
leadingIcon={leadingIcon}
insights={insights}
aria-label={tString(language, 'search_page_result_title', item.title)}
style={{
@@ -91,11 +58,7 @@ export const SearchPageResultItem = React.forwardRef(function SearchPageResultIt
<div
className={tcls(
'relative h-5 w-full transition-[height] duration-300',
item.type === 'local-page' && !preview && !description
? '[[aria-busy=false]_&]:h-0'
: !preview && !description
? 'h-0'
: ''
!preview && !description ? 'h-0' : ''
)}
style={{ transitionDelay: style?.animationDelay }}
>
@@ -119,86 +82,152 @@ export const SearchPageResultItem = React.forwardRef(function SearchPageResultIt
<HighlightQuery query={query} text={description} />
</p>
) : null}
{item.type === 'local-page' ? (
<SkeletonParagraph
size="small"
lines={1}
className={tcls(
'absolute inset-0 origin-left',
preview || description
? 'hidden animate-blur-out'
: '[[aria-busy=false]_&]:hidden [[aria-busy=false]_&]:animate-blur-out'
)}
style={{ animationDelay: style?.animationDelay }}
/>
) : null}
</div>
</SearchResultItem>
);
});
const Breadcrumbs = (props: { breadcrumbs: PageItem['breadcrumbs']; withOverflow?: boolean }) => {
const { breadcrumbs, withOverflow = (breadcrumbs?.length ?? 0) > 4 } = props;
/** Widest a single crumb gets, so one long title can't collapse the rest by itself. */
const CRUMB_MAX_WIDTH = 200;
if (!breadcrumbs || breadcrumbs.length === 0) return null;
/**
* One line of breadcrumbs that shows the whole path when it fits. When it doesn't, the levels next
* to the root fold into a "⋯" in second place, moving toward the result until the line fits; the
* last crumb is cut short only once everything between is folded. The folded levels show on a
* deliberate hover only, so moving the mouse across results doesn't pop them up.
*/
const Breadcrumbs = (props: { breadcrumbs: ComputedPageResult['breadcrumbs'] }) => {
const { breadcrumbs = [] } = props;
const containerRef = React.useRef<HTMLDivElement>(null);
const measureRef = React.useRef<HTMLDivElement>(null);
const [folded, setFolded] = React.useState(0);
const crumbs =
breadcrumbs?.map((crumb) => (
<span key={crumb.label} className="flex items-center gap-1">
{crumb.icon ? <Icon className="size-3" icon={crumb.icon as IconName} /> : null}
{crumb.label}
</span>
)) ?? [];
// Format breadcrumbs for display. Helper function to avoid code duplication across normal and in-tooltip display.
function formatCrumbs(crumbs: React.ReactElement[], className?: string) {
return (
<div
className={tcls(
'transition-colors',
'font-normal',
'flex',
'flex-wrap',
'gap-x-2',
'gap-y-0',
'items-center',
className
)}
>
{crumbs.map((crumb, index) => (
<React.Fragment key={index}>
{index !== 0 ? (
<Icon
key={`${crumb.key}-icon`}
icon="chevron-right"
className="size-2"
/>
) : null}
<span className="line-clamp-1">{crumb}</span>
</React.Fragment>
))}
</div>
const measureFolding = () => {
const container = containerRef.current;
const measure = measureRef.current;
if (!container || !measure) {
return;
}
const widths = Array.from(measure.children, (element) =>
Math.min(element.getBoundingClientRect().width, CRUMB_MAX_WIDTH)
);
}
const ellipsisWidth = widths.pop() ?? 0;
const separatorWidth =
(widths.pop() ?? 0) + 2 * Number.parseFloat(getComputedStyle(container).columnGap);
setFolded(countFoldedCrumbs(widths, container.clientWidth, separatorWidth, ellipsisWidth));
};
// The measuring copy resizes when the labels change, the container when the row does.
useResizeObserver(containerRef, measureFolding);
useResizeObserver(measureRef, measureFolding);
return formatCrumbs(
withOverflow
? [
...crumbs.slice(0, 3),
<Tooltip
key="breadcrumbs-overflow"
label={formatCrumbs(crumbs.slice(3, -1))}
delay={0}
arrow
>
<span>
<Icon key="ellipsis" icon="ellipsis-h" className="size-3" />
</span>
</Tooltip>,
...crumbs.slice(-1),
]
: crumbs,
'text-tint/7 contrast-more:text-tint group-[.is-active]:text-tint text-xs'
const first = breadcrumbs[0];
if (!first) return null;
const hidden = breadcrumbs.slice(1, 1 + folded);
const shown = breadcrumbs.slice(1 + folded);
const separator = <Icon icon="chevron-right" className="size-2 shrink-0" />;
const textClassName = 'text-xs font-normal whitespace-nowrap';
return (
<div
ref={containerRef}
className={tcls(
'relative flex min-w-0 items-center gap-x-2 overflow-hidden text-tint/7 transition-colors group-[.is-active]:text-tint contrast-more:text-tint',
textClassName
)}
>
<div
ref={measureRef}
aria-hidden
className="invisible absolute left-0 top-0 flex items-center"
>
{breadcrumbs.map((crumb, index) => (
<span key={index}>{crumb.label}</span>
))}
{separator}
<Icon icon="ellipsis" className="size-3" />
</div>
<CrumbLabel label={first.label} className="shrink-0" />
{hidden.length > 0 ? (
<>
{separator}
<Tooltip
delay={1000}
label={
<span className="flex flex-col py-0.5">
{hidden.map((crumb, index) => (
<span key={index}>{crumb.label}</span>
))}
</span>
}
>
<span className="flex shrink-0 items-center">
<Icon icon="ellipsis" className="size-3" />
<span className="sr-only">
{hidden.map((crumb) => crumb.label).join(' › ')}
</span>
</span>
</Tooltip>
</>
) : null}
{shown.map((crumb, index) => (
<React.Fragment key={index}>
{separator}
<CrumbLabel
label={crumb.label}
className={index === shown.length - 1 ? 'min-w-[3ch] shrink' : 'shrink-0'}
/>
</React.Fragment>
))}
</div>
);
};
const CrumbLabel = (props: { label: string; className: string }) => {
const { label, className } = props;
const ref = React.useRef<HTMLSpanElement>(null);
const [truncated, setTruncated] = React.useState(false);
useResizeObserver(ref, () => {
const element = ref.current;
if (element) {
setTruncated(element.scrollWidth > element.clientWidth);
}
});
return (
<span
ref={ref}
className={tcls('max-w-[200px] truncate', className)}
title={truncated ? label : undefined}
>
{label}
</span>
);
};
/**
* How many crumbs after the first to fold into the "⋯" so the line fits `available` pixels. The
* first and last crumbs never fold; when even folding everything between doesn't fit, the last
* crumb is cut short instead.
*/
function countFoldedCrumbs(
widths: number[],
available: number,
separatorWidth: number,
ellipsisWidth: number
): number {
const foldable = Math.max(widths.length - 2, 0);
for (let folded = 0; folded <= foldable; folded++) {
const visible = widths.filter((_, index) => index === 0 || index > folded);
const items = visible.length + (folded > 0 ? 1 : 0);
const total =
visible.reduce((sum, width) => sum + width, 0) +
(folded > 0 ? ellipsisWidth : 0) +
(items - 1) * separatorWidth;
if (total <= available + 0.5) {
return folded;
}
}
return foldable;
}
@@ -16,6 +16,8 @@ export const SearchResultItem = React.forwardRef(function SearchResultItem(
size?: 'small' | 'medium';
leadingIcon?: React.ReactNode;
disabled?: boolean;
/** Called when the mouse moves over the item, to make it the selected one. */
onHover?: () => void;
} & LinkInsightsProps &
Omit<React.ComponentProps<typeof Link>, keyof LinkInsightsProps>,
ref: React.Ref<HTMLAnchorElement>
@@ -29,6 +31,7 @@ export const SearchResultItem = React.forwardRef(function SearchResultItem(
size = 'medium',
action,
disabled,
onHover,
...rest
} = props;
@@ -37,6 +40,16 @@ export const SearchResultItem = React.forwardRef(function SearchResultItem(
ref={ref}
href={href ?? '#'}
aria-disabled={disabled}
// Only a real mouse move selects, so rows scrolling under a still pointer don't.
onPointerMove={
onHover && !active
? (event: React.PointerEvent) => {
if (event.pointerType === 'mouse') {
onHover();
}
}
: undefined
}
className={tcls(
'flex',
'items-center',
@@ -46,27 +59,26 @@ export const SearchResultItem = React.forwardRef(function SearchResultItem(
'pr-2',
'py-2',
'text-tint',
disabled ? ['pointer-events-none'] : ['hover:bg-tint', 'hover:text-tint-strong'],
'group',
disabled ? ['pointer-events-none'] : null,
'transition-colors',
'rounded-corners:rounded-md',
'circular-corners:rounded-2xl',
active
? ['is-active', 'bg-primary', 'text-primary-strong', 'hover:bg-primary']
: null,
active ? ['is-active', 'bg-primary', 'text-primary-strong'] : null,
className
)}
role="option"
{...rest}
>
<div className="size-4 shrink-0 text-tint-subtle">
{typeof leadingIcon === 'string' ? (
<Icon icon={leadingIcon as IconName} className="size-4" />
) : (
leadingIcon
)}
</div>
<div className="grow">{children}</div>
{leadingIcon ? (
<div className="size-4 shrink-0 text-tint-subtle">
{typeof leadingIcon === 'string' ? (
<Icon icon={leadingIcon as IconName} className="size-4" />
) : (
leadingIcon
)}
</div>
) : null}
<div className="min-w-0 grow">{children}</div>
{disabled ? null : active ? (
<Button
label={action}
@@ -4,27 +4,39 @@ import assertNever from 'assert-never';
import { motion } from 'framer-motion';
import React from 'react';
import { Button, SkeletonParagraph, SkeletonSmall } from '../primitives';
import { Button } from '../primitives';
import { isExternalLink } from '../utils/link';
import { addRecentSearchQuery } from './recent-queries';
import { SearchPageResultItem } from './SearchPageResultItem';
import { SearchQuestionResultItem } from './SearchQuestionResultItem';
import { SearchRecordResultItem } from './SearchRecordResultItem';
import { SearchResultItem } from './SearchResultItem';
import type { ResultType } from './useSearchResults';
import { useAI } from '@/components/AI';
import { useCurrentContent } from '@/components/hooks';
import { t, useLanguage } from '@/intl/client';
import { tcls } from '@/lib/tailwind';
/**
* Bar widths (breadcrumb, title, description, in %) of the loading placeholder rows. Six rows of
* this height fill the results area of the desktop popover; the count never depends on an answer.
*/
const PLACEHOLDER_ROWS: [crumb: number, title: number, description: number][] = [
[28, 64, 86],
[20, 48, 78],
[34, 58, 90],
[24, 70, 72],
[30, 52, 84],
[22, 60, 76],
];
export interface SearchResultsRef {
select(): boolean;
/** Activate the first result, ignoring the cursor. */
selectFirst(): boolean;
}
function getResultKey(item: ResultType): string {
switch (item.type) {
case 'local-page':
return `page:${item.id}`;
case 'page':
return `page:${item.pageId}`;
case 'record':
@@ -51,10 +63,12 @@ export const SearchResults = React.forwardRef(function SearchResults(
cursor: number | null;
error: boolean;
onResultSelect?: () => void;
onResultHover?: (index: number) => void;
},
ref: React.Ref<SearchResultsRef>
) {
const { children, id, query, results, fetching, cursor, error, onResultSelect } = props;
const { children, id, query, results, fetching, cursor, error, onResultSelect, onResultHover } =
props;
const language = useLanguage();
const { siteSpaceId } = useCurrentContent();
@@ -69,6 +83,7 @@ export const SearchResults = React.forwardRef(function SearchResults(
}
const refs = React.useRef<(null | HTMLAnchorElement)[]>([]);
const selectedByPointer = React.useRef(false);
React.useEffect(() => {
for (const item of results) {
@@ -76,8 +91,12 @@ export const SearchResults = React.forwardRef(function SearchResults(
}
}, [results]);
// Scroll to the active result.
// Scroll to the active result, unless the mouse picked it: it is already under the pointer.
React.useEffect(() => {
if (selectedByPointer.current) {
selectedByPointer.current = false;
return;
}
if (cursor === null || !refs.current[cursor]) {
return;
}
@@ -107,6 +126,11 @@ export const SearchResults = React.forwardRef(function SearchResults(
ref,
() => ({
select,
selectFirst: () => {
const first = refs.current[0];
first?.click();
return Boolean(first);
},
}),
[select]
);
@@ -114,7 +138,7 @@ export const SearchResults = React.forwardRef(function SearchResults(
const { assistants } = useAI();
const primaryAssistant = assistants[0];
if (error && results.length === 0) {
if (error) {
return (
<output
className={tcls(
@@ -157,26 +181,6 @@ export const SearchResults = React.forwardRef(function SearchResults(
</output>
);
const partialError = error ? (
<div
className={tcls(
'mt-3',
'rounded-corners:rounded-md',
'circular-corners:rounded-2xl',
'bg-tint-subtle',
'px-3',
'py-2',
'text-center',
'text-sm',
'text-tint-subtle',
'animate-blur-in-slow'
)}
role="status"
>
{t(language, 'search_partial_error')}
</div>
) : null;
return (
<output className="flex grow flex-col" aria-busy={fetching}>
{children}
@@ -202,10 +206,7 @@ export const SearchResults = React.forwardRef(function SearchResults(
const handleResultSelect = (
event: React.MouseEvent<HTMLAnchorElement>
) => {
const isPageResult =
item.type === 'local-page' ||
item.type === 'page' ||
item.type === 'record';
const isPageResult = item.type === 'page' || item.type === 'record';
if (
isPageResult &&
@@ -236,9 +237,14 @@ export const SearchResults = React.forwardRef(function SearchResults(
'aria-setsize': results.length,
id: `${id}-${index}`,
onClickCapture: handleResultSelect,
onHover: onResultHover
? () => {
selectedByPointer.current = true;
onResultHover(index);
}
: undefined,
};
switch (item.type) {
case 'local-page':
case 'page': {
return (
<motion.div
@@ -353,49 +359,61 @@ export const SearchResults = React.forwardRef(function SearchResults(
{!fetching && results.length === 0 ? noResults : null}
</>
)}
{partialError}
{fetching ? (
<div
role="status"
aria-busy="true"
className={tcls(
results.length > 0 ? 'mt-1' : '',
'flex animate-blur-in flex-col gap-1'
'flex flex-col gap-1',
'animate-[fadeIn_150ms_ease-out_both,pulse_2.4s_ease-in-out_600ms_infinite] motion-reduce:animate-none'
)}
style={{ animationDelay: `${results.length * 25}ms` }}
>
<SearchResultsSkeleton items={Math.max(3, 5 - results.length)} />
<SearchResultsPlaceholder />
</div>
) : null}
</output>
);
});
const SearchResultsSkeleton = (props: { items: number }) => {
const { items } = props;
const skeletonKeys = Array.from({ length: items }, (_, index) => `skeleton:${index}`);
/**
* Loading rows shaped like a page result: breadcrumb, title and description lines in the real
* row's box, so the first result lands where the first placeholder was.
*/
const SearchResultsPlaceholder = () =>
PLACEHOLDER_ROWS.map(([crumb, title, description], index) => (
<div
key={index}
data-search-placeholder-row
aria-hidden
className="flex items-center gap-3 py-2 pl-3 pr-2"
>
<div className="grow">
<PlaceholderLine className="text-xs" barClassName="h-2" width={crumb} />
<PlaceholderLine
className="font-heading text-base font-semibold leading-snug"
barClassName="h-3.5 bg-tint-solid/3"
width={title}
/>
<PlaceholderLine className="h-5 text-sm" barClassName="h-2.5" width={description} />
</div>
<div className="size-7 shrink-0" />
</div>
));
return (
<>
{skeletonKeys.map((key, index) => (
<SearchResultItem
key={key}
active={false}
href="#"
action=""
disabled
data-testid="search-page-result"
leadingIcon={
<SkeletonSmall
className="size-4"
style={{ animationDelay: `${index * 0.3}s` }}
/>
}
>
<SkeletonParagraph size="small" start={index * 3} />
</SearchResultItem>
))}
</>
);
};
/** One text line of a placeholder row: the line box of the real text, with a bar inside it. */
const PlaceholderLine = (props: { className: string; barClassName: string; width: number }) => (
<div className={tcls('relative', props.className)}>
{'\u00a0'}
<div
className={tcls(
'absolute inset-y-0 left-0 my-auto rounded-full bg-tint-solid/2',
props.barClassName
)}
style={{ width: `${props.width}%` }}
/>
</div>
);
/**
* Whether clicking a result navigates the current window, and so closes the search — as opposed
@@ -1,6 +1,7 @@
import { describe, expect, it } from 'bun:test';
import { computeFilterSiteSpaceIds } from './filter';
import { computeFilterSiteSpaceIds, filterResultsBySiteSpaces } from './filter';
import type { OrderedComputedResult } from './search-types';
describe('computeFilterSiteSpaceIds', () => {
const currentId = 'space-current';
@@ -34,3 +35,31 @@ describe('computeFilterSiteSpaceIds', () => {
expect(r).toEqual(['space-other-a', 'space-other-b']);
});
});
describe('filterResultsBySiteSpaces', () => {
const page = (id: string, siteSpaceId?: string): OrderedComputedResult => ({
type: 'page',
id,
title: id,
href: `/${id}`,
score: 1,
pageId: id,
spaceId: 'space',
siteSpaceId,
description: '',
rank: 1,
});
it('keeps the server order and drops pages outside the scope', () => {
const results = [page('a', 'current'), page('b', 'other'), page('c', 'current'), page('d')];
expect(filterResultsBySiteSpaces(results, ['current']).map((result) => result.id)).toEqual([
'a',
'c',
]);
});
it('returns every result when the scope is unrestricted', () => {
const results = [page('b', 'other'), page('a', 'current')];
expect(filterResultsBySiteSpaces(results, undefined)).toBe(results);
});
});
@@ -1,16 +1,13 @@
import type { OrderedComputedResult } from './search-types';
import type { SearchScope } from './useSearch';
/**
* Map UI search scope to local FlexSearch filtering.
* Site spaces whose pages may be shown for a UI search scope, or `undefined` for no restriction.
*
* Rationale: when a site has no sections (only variants), the remote search
* "default" scope effectively queries the current variant. To keep local
* results consistent with remote ones, we also restrict "default" to the
* current `siteSpaceId` when `withSections` is false. Otherwise (sections
* present), local "default" stays unfiltered to match the broader section UI.
* An explicitly selected section takes precedence over these legacy scopes.
* The server's "default" scope also returns pages from other site spaces. Without sections
* (only variants) the UI presents "default" as the current variant, so it is restricted to
* the current `siteSpaceId`. An explicitly selected section takes precedence.
*/
export function computeFilterSiteSpaceIds(
scope: SearchScope,
siteSpaceId: string,
@@ -31,3 +28,21 @@ export function computeFilterSiteSpaceIds(
return withSections ? undefined : [siteSpaceId];
}
}
/** Keep the server's order, dropping pages owned by a site space outside the scope. */
export function filterResultsBySiteSpaces(
results: OrderedComputedResult[],
allowedSiteSpaceIds: string[] | undefined
): OrderedComputedResult[] {
if (!allowedSiteSpaceIds) {
return results;
}
const allowed = new Set(allowedSiteSpaceIds);
return results.filter(
(result) =>
result.type === 'record' ||
(result.siteSpaceId !== undefined && allowed.has(result.siteSpaceId))
);
}
@@ -5,5 +5,4 @@ export * from './SearchContainer';
export * from './SearchScopeControl';
export * from './search-props';
export * from './useSearch';
export * from './useLocalSearchResults';
export * from './useSearchController';
@@ -1,239 +0,0 @@
import { describe, expect, it } from 'bun:test';
import {
type MergedPageResult,
fuseSearchResults,
getResultKey,
reciprocalRankFusion,
} from './reciprocalRankFusion';
import type { OrderedComputedResult } from './search-types';
import type { LocalPageResult } from './useLocalSearchResults';
function localPage(id: string, title = id, siteSpaceId = 'site-space-alpha'): LocalPageResult {
return {
type: 'local-page',
id,
siteSpaceId,
title,
pathname: `/${id}`,
description: `Local description for ${title}`,
breadcrumbs: [{ label: 'Local', icon: 'book-open' }],
};
}
function remotePage(
id: string,
title = id,
score = 0,
rank = 1,
spaceId = 'space-alpha',
siteSpaceId = 'site-space-alpha'
): OrderedComputedResult {
return {
type: 'page',
id: `remote-${id}`,
pageId: id,
spaceId,
siteSpaceId,
title,
description: `Remote description for ${title}`,
href: `/${id}`,
score,
rank,
breadcrumbs: [{ label: 'Remote' }],
};
}
function remoteRecord(id: string, title = id): OrderedComputedResult {
return {
type: 'record',
id,
title,
href: `/records/${id}`,
score: 0,
description: undefined,
};
}
describe('reciprocalRankFusion', () => {
it('keeps the first 3 remote results first and in remote order', () => {
const results = reciprocalRankFusion(
[localPage('local-match', 'Alpha Local Match')],
[
remotePage('remote-1'),
remoteRecord('remote-2'),
remotePage('remote-3'),
remotePage('remote-4'),
],
'alpha'
);
expect(results.slice(0, 3).map(getResultKey)).toEqual([
'page:remote-1',
'record:remote-2',
'page:remote-3',
]);
});
it('applies fusion only after the pinned remote results', () => {
const results = reciprocalRankFusion(
[localPage('local-match', 'Alpha Local Match')],
[
remotePage('remote-1'),
remotePage('remote-2'),
remotePage('remote-3'),
remotePage('remote-4'),
],
'alpha'
);
expect(results.slice(0, 3).map(getResultKey)).toEqual([
'page:remote-1',
'page:remote-2',
'page:remote-3',
]);
const firstFusedResult = results[3];
if (!firstFusedResult) {
throw new Error('Expected a fused result after the pinned remote results');
}
expect(getResultKey(firstFusedResult)).toBe('page:local-match');
});
it('pins all remote results when fewer than 3 are present', () => {
const results = reciprocalRankFusion(
[localPage('local-match', 'Alpha Local Match')],
[remoteRecord('remote-1'), remotePage('remote-2')],
'alpha'
);
expect(results.map(getResultKey)).toEqual([
'record:remote-1',
'page:remote-2',
'page:local-match',
]);
});
it('merges a pinned remote page with the matching local page without duplicating it', () => {
const results = reciprocalRankFusion(
[localPage('remote-1', 'Local title')],
[
remotePage('remote-1', 'Remote title', 1, 1),
remotePage('remote-2'),
remotePage('remote-3'),
],
'remote'
);
const pinnedResult = results[0] as MergedPageResult;
expect(pinnedResult.type).toBe('page');
expect(pinnedResult.title).toBe('Remote title');
expect(pinnedResult.pathname).toBe('/remote-1');
expect(pinnedResult.description).toBe('Remote description for Remote title');
expect(pinnedResult.rank).toBe(1);
expect(pinnedResult.breadcrumbs).toEqual([{ label: 'Local', icon: 'book-open' }]);
expect(results.map(getResultKey).filter((key) => key === 'page:remote-1')).toHaveLength(1);
});
it('does not duplicate pinned records in the fused tail', () => {
const results = reciprocalRankFusion(
[],
[
remoteRecord('record-1'),
remotePage('remote-2'),
remotePage('remote-3'),
remoteRecord('record-1'),
remotePage('remote-4'),
],
'remote'
);
expect(results.map(getResultKey).filter((key) => key === 'record:record-1')).toHaveLength(
1
);
});
});
describe('fuseSearchResults', () => {
it('filters every source to the current site space before fusion', () => {
const results = fuseSearchResults({
localResults: [
localPage('local-alpha', 'Alpha local result'),
localPage('remote-alpha-1', 'Beta local result', 'site-space-beta'),
],
remoteResults: [
remotePage('remote-alpha-1', 'Alpha remote one', 10, 1),
remotePage(
'local-alpha',
'Beta remote result',
9,
2,
'space-beta',
'site-space-beta'
),
remotePage('remote-alpha-2', 'Alpha remote two', 8, 3),
],
query: 'result',
allowedSiteSpaceIds: ['site-space-alpha'],
});
expect(results.map(getResultKey)).toEqual([
'page:remote-alpha-1',
'page:remote-alpha-2',
'page:local-alpha',
]);
expect(results[0]).not.toHaveProperty('pathname');
expect(results[2]?.type).toBe('local-page');
});
it('preserves cross-site-space results when the search is unrestricted', () => {
const results = fuseSearchResults({
localResults: [
localPage('local-alpha', 'Alpha local result'),
localPage('local-beta', 'Beta local result', 'site-space-beta'),
],
remoteResults: [
remotePage('remote-alpha', 'Alpha remote result', 10, 1),
remotePage(
'remote-beta',
'Beta remote result',
9,
2,
'space-beta',
'site-space-beta'
),
],
query: 'result',
});
expect(results.map(getResultKey)).toEqual([
'page:remote-alpha',
'page:remote-beta',
'page:local-alpha',
'page:local-beta',
]);
});
it('preserves every allowed site space in an intentionally multi-space search', () => {
const results = fuseSearchResults({
localResults: [
localPage('local-alpha'),
localPage('local-beta', 'local-beta', 'site-space-beta'),
localPage('local-gamma', 'local-gamma', 'site-space-gamma'),
],
remoteResults: [
remotePage('remote-alpha'),
remotePage('remote-beta', 'remote-beta', 0, 2, 'space-beta', 'site-space-beta'),
remotePage('remote-gamma', 'remote-gamma', 0, 3, 'space-gamma', 'site-space-gamma'),
],
query: 'page',
allowedSiteSpaceIds: ['site-space-alpha', 'site-space-beta'],
});
expect(results.map(getResultKey)).toEqual([
'page:remote-alpha',
'page:remote-beta',
'page:local-alpha',
'page:local-beta',
]);
});
});
@@ -1,271 +0,0 @@
import type { ComputedPageResult, OrderedComputedResult } from './search-types';
import type { LocalPageResult } from './useLocalSearchResults';
/**
* Jaro-Winkler similarity between two strings, in the range [0, 1].
* Higher is more similar. 1 means an exact match.
* https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance
*/
function jaroWinkler(s1: string, s2: string, p = 0.1): number {
if (s1 === s2) return 1;
const len1 = s1.length;
const len2 = s2.length;
if (len1 === 0 || len2 === 0) return 0;
const maxDist = Math.floor(Math.max(len1, len2) / 2) - 1;
const matched1 = new Array<boolean>(len1);
const matched2 = new Array<boolean>(len2);
for (let i = 0; i < len1; i++) matched1[i] = false;
for (let i = 0; i < len2; i++) matched2[i] = false;
let matches = 0;
for (let i = 0; i < len1; i++) {
const start = Math.max(0, i - maxDist);
const end = Math.min(len2 - 1, i + maxDist);
for (let j = start; j <= end; j++) {
if (!matched2[j] && s1.charCodeAt(i) === s2.charCodeAt(j)) {
matched1[i] = true;
matched2[j] = true;
matches++;
break;
}
}
}
if (matches === 0) return 0;
let t = 0;
let k = 0;
for (let i = 0; i < len1; i++) {
if (!matched1[i]) continue;
while (!matched2[k]) k++;
if (s1.charCodeAt(i) !== s2.charCodeAt(k)) t++;
k++;
}
const transpositions = t / 2;
const m = matches;
const jaro = (m / len1 + m / len2 + (m - transpositions) / m) / 3;
let prefix = 0;
const maxPrefix = 4;
const minLen = Math.min(len1, len2);
for (let i = 0; i < maxPrefix && i < minLen; i++) {
if (s1.charCodeAt(i) === s2.charCodeAt(i)) prefix++;
else break;
}
return jaro + prefix * p * (1 - jaro);
}
/** Standard RRF constant — moderates the impact of high-ranked items. */
const RRF_K = 60;
/** Lower k for local results gives them a slightly higher score than remote ones at the same rank. */
const RRF_K_LOCAL = 50;
/** Number of remote results that should keep their API order before fusion. */
const PINNED_REMOTE_RESULTS_COUNT = 3;
/**
* A page result that was present in both local and remote lists.
* Local fields (icon, emoji, pathname) are carried over as a base, and remote fields
* (description, href, pageId, spaceId, title) override them.
* Breadcrumbs prefer local (has icon + emoji) and fall back to remote.
*/
export type MergedPageResult = Omit<ComputedPageResult, 'breadcrumbs'> & {
pathname?: string;
icon?: string;
emoji?: string;
breadcrumbs?: LocalPageResult['breadcrumbs'] | ComputedPageResult['breadcrumbs'];
};
/**
* Derive a stable deduplication key for any result type.
* Pages from both local and remote share the same `page:` namespace so they
* can be deduplicated against each other.
*/
export function getResultKey(
result: LocalPageResult | OrderedComputedResult | MergedPageResult
): string {
switch (result.type) {
case 'local-page':
return `page:${result.id}`;
case 'page':
return `page:${result.pageId}`;
case 'record':
return `record:${result.id}`;
}
}
type RRFResult = LocalPageResult | OrderedComputedResult | MergedPageResult;
/** Filter page candidates at the final assembly boundary, immediately before ranking and fusion. */
export function fuseSearchResults(args: {
localResults: LocalPageResult[];
remoteResults: OrderedComputedResult[];
query: string;
allowedSiteSpaceIds?: string[];
}): RRFResult[] {
const { localResults, remoteResults, query, allowedSiteSpaceIds } = args;
if (!allowedSiteSpaceIds) {
return reciprocalRankFusion(localResults, remoteResults, query);
}
const allowed = new Set(allowedSiteSpaceIds);
return reciprocalRankFusion(
localResults.filter((result) => allowed.has(result.siteSpaceId)),
remoteResults.filter(
(result) =>
result.type === 'record' ||
(result.siteSpaceId !== undefined && allowed.has(result.siteSpaceId))
),
query
);
}
function mergeLocalPageWithRemotePage(
localResult: LocalPageResult,
remoteResult: ComputedPageResult
): MergedPageResult {
return {
...localResult,
...remoteResult,
// Merge breadcrumbs: prefer local (has icon + emoji), fall back to remote.
breadcrumbs: localResult.breadcrumbs ?? remoteResult.breadcrumbs,
};
}
function mergePinnedRemoteResult(
result: OrderedComputedResult,
localResultsByKey: Map<string, LocalPageResult>
): RRFResult {
if (result.type !== 'page') {
return result;
}
const localResult = localResultsByKey.get(getResultKey(result));
if (!localResult) {
return result;
}
return mergeLocalPageWithRemotePage(localResult, result);
}
/**
* Merge local (FlexSearch) and remote (API) search results using
* Reciprocal Rank Fusion (RRF), while preserving the order of the first
* three remote results.
*
* RRF formula: score(d) = Σ_i 1 / (k + rank_i(d))
*
* The pinned remote results are excluded from fusion and returned first. Pages
* present in both lists are deep-merged: local fields act as the base
* (preserving icon, emoji, pathname) and remote fields override (providing the
* authoritative page description, href, pageId, spaceId, and title). Breadcrumbs prefer local (has icon
* + emoji) and fall back to remote. In the fused tail, their rank contributions
* from both lists are summed.
*
* Sections and records have no local equivalent and only accumulate their own
* rank contribution.
*
* Additionally, a Jaro-Winkler title-match bonus is applied per query word:
* for each query word that appears as a substring in the title, the best
* Jaro-Winkler similarity score against any individual title word is added.
*/
export function reciprocalRankFusion(
localResults: LocalPageResult[],
remoteResults: OrderedComputedResult[],
query: string
): RRFResult[] {
const localResultsByKey = new Map(localResults.map((result) => [getResultKey(result), result]));
const pinnedRemoteResults = remoteResults.slice(0, PINNED_REMOTE_RESULTS_COUNT);
const pinnedResultKeys = new Set(pinnedRemoteResults.map((result) => getResultKey(result)));
const remainingLocalResults = localResults.filter(
(result) => !pinnedResultKeys.has(getResultKey(result))
);
const remainingRemoteResults = remoteResults
.slice(PINNED_REMOTE_RESULTS_COUNT)
.filter((result) => !pinnedResultKeys.has(getResultKey(result)));
// Map from dedup key → { result, score }
const scoreMap = new Map<string, { result: RRFResult; score: number }>();
// Process local results first (1-indexed rank)
// Using RRF_K_LOCAL (< RRF_K) slightly boosts local scores over remote ones.
remainingLocalResults.forEach((result, index) => {
const rank = index + 1;
const key = getResultKey(result);
const contribution = 1 / (RRF_K_LOCAL + rank);
const existing = scoreMap.get(key);
if (existing) {
existing.score += contribution;
} else {
scoreMap.set(key, { result, score: contribution });
}
});
// Process remote results, deduplicating against local pages
remainingRemoteResults.forEach((result, index) => {
const rank = index + 1;
const contribution = 1 / (RRF_K + rank);
const key = getResultKey(result);
const existing = scoreMap.get(key);
if (existing) {
// Page found in both lists: sum rank contributions and deep-merge.
// Local is the base (icon, emoji, pathname), while remote provides page fields.
existing.score += contribution;
if (existing.result.type === 'local-page' && result.type === 'page') {
existing.result = mergeLocalPageWithRemotePage(existing.result, result);
} else {
existing.result = result;
}
} else {
scoreMap.set(key, { result, score: contribution });
}
});
// Apply a title-match bonus per query word using Jaro-Winkler similarity.
// For each query word that appears (as a substring) in the title, compute the
// best Jaro-Winkler score against individual title words and add it to the score.
const queryWords = query
.toLowerCase()
.split(/\s+/)
.filter((w) => w.length > 0);
if (queryWords.length > 0) {
for (const entry of scoreMap.values()) {
// Only apply the bonus to page or local-page results
if (entry.result.type === 'record') continue;
const title = entry.result.title?.toLowerCase() ?? '';
const titleWords = title.split(/\s+/).filter((w) => w.length > 0);
for (const word of queryWords) {
// Only apply when there is at least a substring match in the title.
if (!title.includes(word)) continue;
let best = 0;
for (const titleWord of titleWords) {
const sim = jaroWinkler(word, titleWord);
if (sim > best) best = sim;
}
entry.score += best;
}
}
}
// Sort descending by RRF score
const fusedResults = Array.from(scoreMap.values())
.sort((a, b) => b.score - a.score)
.map(({ result }) => result);
return [
...pinnedRemoteResults.map((result) => mergePinnedRemoteResult(result, localResultsByKey)),
...fusedResults,
];
}
@@ -0,0 +1,139 @@
import { afterEach, describe, expect, it, spyOn } from 'bun:test';
import { createSearchPassStore } from './search-pass-store';
import type { DirectSearchProps } from '@/lib/search-results';
const endpoint = 'https://api.gitbook.com/v1/orgs/org_1/sites/site_1/search';
const directSearch: DirectSearchProps = {
apiURL: 'https://api.gitbook.com',
organizationId: 'org_1',
siteId: 'site_1',
linker: {
urlMode: 'url-host',
siteHost: 'docs.example.com',
siteBasePath: '/',
spaceBasePath: '/',
gitbookURL: undefined,
},
spaces: {},
passURL: '/~gitbook/search-pass',
};
/** Answer each pass request with a new pass, and each API search with the next status. */
function mockFetch(apiStatuses: number[], passLifetimesMs: number[] = []) {
const authorizations: (string | null)[] = [];
let passes = 0;
const fetchSpy = spyOn(globalThis, 'fetch').mockImplementation((async (
input: RequestInfo | URL,
init?: RequestInit
) => {
if (init?.signal?.aborted) {
throw new DOMException('Aborted', 'AbortError');
}
if (String(input) === '/~gitbook/search-pass') {
passes += 1;
return Response.json({
token: `pass-${passes}`,
expiresIn: passLifetimesMs.shift() ?? 300_000,
});
}
expect(String(input)).toBe(endpoint);
authorizations.push(new Headers(init?.headers).get('authorization'));
const status = apiStatuses.shift() ?? 200;
return status === 200 ? Response.json({ items: [] }) : new Response(null, { status });
}) as typeof fetch);
return { authorizations, fetchSpy };
}
function search(store: ReturnType<typeof createSearchPassStore>, signal?: AbortSignal) {
return store.search({
query: 'tokens',
scope: { mode: 'all' },
signal: signal ?? new AbortController().signal,
asEmbeddable: false,
});
}
describe('createSearchPassStore', () => {
let restore: (() => void) | undefined;
afterEach(() => restore?.());
it('stays on the route for the rest of the page after a 403', async () => {
const { authorizations, fetchSpy } = mockFetch([403]);
restore = () => fetchSpy.mockRestore();
const store = createSearchPassStore(directSearch);
await store.requestPass();
expect(await search(store)).toEqual({ type: 'route', reason: '403' });
await store.requestPass();
expect(await search(store)).toEqual({ type: 'route', reason: '403' });
expect(authorizations).toHaveLength(1);
});
it.each([
['an expired pass', [], [1_000], 'expired', ['Bearer pass-2']],
['a 401', [401], [], '401', ['Bearer pass-1', 'Bearer pass-2']],
])(
'sends the search to the route on %s and searches directly again with a new pass',
async (_name, apiStatuses, passLifetimesMs, reason, sent) => {
const { authorizations, fetchSpy } = mockFetch(apiStatuses, passLifetimesMs);
restore = () => fetchSpy.mockRestore();
const store = createSearchPassStore(directSearch);
await store.requestPass();
expect(await search(store)).toEqual({ type: 'route', reason });
await new Promise((resolve) => setTimeout(resolve, 0));
expect(await search(store)).toEqual({ type: 'results', results: [] });
expect(authorizations).toEqual(sent);
}
);
it('keeps the one-refresh bound when a 401 arrives while a refresh is pending', async () => {
const replies = {
search: Promise.withResolvers<Response>(),
pass: Promise.withResolvers<Response>(),
};
let passRequests = 0;
const fetchSpy = spyOn(globalThis, 'fetch').mockImplementation((async (
input: RequestInfo | URL
) => {
if (String(input) === '/~gitbook/search-pass') {
passRequests += 1;
return passRequests === 2
? replies.pass.promise
: Response.json({ token: `pass-${passRequests}`, expiresIn: 300_000 });
}
return passRequests === 1
? replies.search.promise
: new Response(null, { status: 401 });
}) as typeof fetch);
restore = () => fetchSpy.mockRestore();
const store = createSearchPassStore(directSearch);
await store.requestPass();
const inFlight = search(store);
const refresh = store.requestPass();
replies.search.resolve(new Response(null, { status: 401 }));
expect(await inFlight).toEqual({ type: 'route', reason: '401' });
replies.pass.resolve(Response.json({ token: 'pass-2', expiresIn: 300_000 }));
await refresh;
expect(await search(store)).toEqual({ type: 'route', reason: '401' });
expect(passRequests).toBe(2);
});
it('neither retries nor falls back when the search is aborted', async () => {
const { authorizations, fetchSpy } = mockFetch([]);
restore = () => fetchSpy.mockRestore();
const store = createSearchPassStore(directSearch);
await store.requestPass();
const controller = new AbortController();
controller.abort();
await expect(search(store, controller.signal)).rejects.toThrow();
expect(await search(store)).toEqual({ type: 'results', results: [] });
expect(authorizations).toHaveLength(1);
});
});
@@ -0,0 +1,258 @@
import ReactDOM from 'react-dom';
import type { SearchRecordResult, SearchSpaceResult } from '@gitbook/api';
import type { OrderedComputedResult, SearchSiteContentScope } from './search-types';
import { getEmbeddableLinker } from '@/lib/embeddable-linker';
import { createSiteLinker } from '@/lib/links';
import {
type DirectSearchProps,
computePublishedSearchResults,
toSearchSiteContentBody,
} from '@/lib/search-results';
/** Request header on a search route call naming why the search did not go to the API. */
export const SEARCH_FALLBACK_HEADER = 'x-gitbook-search-fallback';
const PASS_REQUEST_TIMEOUT_MS = 3_000;
const EXPIRY_MARGIN_MS = 5_000;
const RATE_LIMIT_WAIT_MS = 2_000;
// The longest shared rate limit window of the search API.
const RATE_LIMIT_MAX_WAIT_MS = 60_000;
const DIRECT_SEARCH_TIMEOUT_MS = 5_000;
// Which limit answered a 429: `caller` is the pass's own, `capacity` a saturated index.
const RATE_LIMIT_SCOPE_HEADER = 'x-ratelimit-scope';
type SearchPassState =
| { status: 'none'; reason?: string }
| { status: 'ready'; token: string; expiresAt: number; replacesRejectedPass: boolean }
| { status: 'route'; reason: string; cooldownUntil: number };
type DirectSearchOutcome =
| { type: 'results'; results: OrderedComputedResult[] }
| { type: 'route'; reason?: string };
export type SearchPassStore = ReturnType<typeof createSearchPassStore>;
/**
* Hold a search pass from the site's search pass route in memory, and search the API with it.
*/
export function createSearchPassStore(directSearch: DirectSearchProps | undefined) {
let state: SearchPassState = { status: 'none' };
let pendingRequest: Promise<void> | null = null;
const sendPassRequest = async () => {
if (!directSearch || state.status === 'route') {
return;
}
// The held pass may belong to a session that has since ended, so it waits for the reply.
if (state.status === 'ready') {
state = state.replacesRejectedPass
? { status: 'none', reason: '401' }
: { status: 'none' };
}
const request = new AbortController();
const timeout = setTimeout(() => request.abort(), PASS_REQUEST_TIMEOUT_MS);
try {
const response = await fetch(directSearch.passURL, {
method: 'POST',
signal: request.signal,
});
const { token, expiresIn } =
response.status === 200
? ((await response.json()) as { token?: unknown; expiresIn?: unknown })
: {};
// A search may have moved the page to the route while this request was in flight.
const current = state as SearchPassState;
if (
current.status !== 'route' &&
typeof token === 'string' &&
typeof expiresIn === 'number'
) {
state = {
status: 'ready',
token,
expiresAt: Date.now() + expiresIn,
replacesRejectedPass:
(current.status === 'none' && current.reason === '401') ||
(current.status === 'ready' && current.replacesRejectedPass),
};
ReactDOM.preconnect(directSearch.apiURL, { crossOrigin: 'anonymous' });
} else if (current.status === 'ready') {
state = { status: 'none' };
}
if (!response.ok) {
throw new Error(`Search pass request failed: ${response.status}`);
}
} catch (error) {
const current = state as SearchPassState;
// Keep the 401 so a later replacement pass is still refused only once.
if (
current.status === 'ready' ||
(current.status === 'none' && current.reason !== '401')
) {
state = { status: 'none', reason: 'pass_request' };
}
throw error;
} finally {
clearTimeout(timeout);
}
};
const requestPass = () => {
pendingRequest ??= sendPassRequest().finally(() => {
pendingRequest = null;
});
return pendingRequest;
};
const dropPass = (token: string, reason: string): DirectSearchOutcome => {
if (state.status === 'ready' && state.token === token) {
state = { status: 'none', reason };
void requestPass().catch(() => undefined);
} else if (state.status === 'none' && reason === '401') {
// The pass was suspended for a pending request: its reply must still see the rejection.
state = { status: 'none', reason };
}
return { type: 'route', reason };
};
const fallBack = (reason: string): DirectSearchOutcome => {
state = { status: 'route', reason, cooldownUntil: 0 };
return { type: 'route', reason };
};
const search = async (input: {
query: string;
scope: SearchSiteContentScope;
signal: AbortSignal;
asEmbeddable: boolean;
}): Promise<DirectSearchOutcome> => {
const { query, scope, signal, asEmbeddable } = input;
if (!directSearch) {
return { type: 'route' };
}
if (state.status === 'ready' && state.expiresAt - Date.now() <= EXPIRY_MARGIN_MS) {
return dropPass(state.token, 'expired');
}
if (state.status === 'route') {
return waitForCooldown(state, signal);
}
if (state.status !== 'ready') {
return { type: 'route', reason: state.reason };
}
if (query.length <= 1) {
return { type: 'results', results: [] };
}
const { token, replacesRejectedPass } = state;
const { apiURL, organizationId, siteId } = directSearch;
// A request dropped on the way to the API never settles, so it gets its own time limit.
// The browser targets predate `AbortSignal.any`.
const request = new AbortController();
if (signal.aborted) {
request.abort();
}
signal.addEventListener('abort', () => request.abort(), { once: true });
const timeout = setTimeout(() => request.abort(), DIRECT_SEARCH_TIMEOUT_MS);
let response: Response;
try {
response = await fetch(`${apiURL}/v1/orgs/${organizationId}/sites/${siteId}/search`, {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(toSearchSiteContentBody(query, scope)),
credentials: 'omit',
signal: request.signal,
});
} catch (error) {
if (signal.aborted) {
throw error;
}
return fallBack(request.signal.aborted ? 'timeout' : 'network');
}
if (response.status === 401) {
return replacesRejectedPass ? fallBack('401') : dropPass(token, '401');
}
if (response.status === 429) {
state = {
status: 'route',
reason: '429',
cooldownUntil: Date.now() + getRateLimitWaitMs(response),
};
return waitForCooldown(state, signal);
}
if (!response.ok) {
return fallBack(String(response.status));
}
let results: OrderedComputedResult[] | null;
try {
const { items } = (await response.json()) as {
items: (SearchSpaceResult | SearchRecordResult)[];
};
const linker = createSiteLinker(directSearch.linker);
results = computePublishedSearchResults({
asEmbeddable,
linker: asEmbeddable ? getEmbeddableLinker(linker) : linker,
searchResults: items,
spaces: directSearch.spaces,
});
} catch (error) {
if (signal.aborted) {
throw error;
}
return fallBack(request.signal.aborted ? 'timeout' : 'invalid');
} finally {
clearTimeout(timeout);
}
return results ? { type: 'results', results } : fallBack('unknown_space');
};
return { requestPass, search };
}
/**
* Hold a search until a short rate limit cooldown ends, then send it to the route.
* During a longer cooldown the search fails at once, as the route would.
*/
async function waitForCooldown(
route: Extract<SearchPassState, { status: 'route' }>,
signal: AbortSignal
): Promise<DirectSearchOutcome> {
const waitMs = route.cooldownUntil - Date.now();
if (waitMs > RATE_LIMIT_WAIT_MS) {
throw new Error('Search is rate limited');
}
if (waitMs > 0) {
await new Promise((resolve) => setTimeout(resolve, waitMs));
if (signal.aborted) {
throw new DOMException('Search aborted', 'AbortError');
}
}
return { type: 'route', reason: route.reason };
}
/**
* How long to hold searches after a 429: until the API's rate limit resets, when it says so.
*/
function getRateLimitWaitMs(response: Response): number {
switch (response.headers.get(RATE_LIMIT_SCOPE_HEADER)) {
// The route does not use the pass, and an unnamed limit may come from an older API.
case null:
case 'caller':
case 'capacity':
return RATE_LIMIT_WAIT_MS;
default: {
const resetSeconds = Number(response.headers.get('x-ratelimit-reset'));
if (!resetSeconds) {
return RATE_LIMIT_WAIT_MS;
}
return Math.min(Math.max(resetSeconds * 1000 - Date.now(), 0), RATE_LIMIT_MAX_WAIT_MS);
}
}
}

Some files were not shown because too many files have changed in this diff Show More