feat(js)!: expose instance API + lifecycle callbacks

[dylantientcheu]

Summary

• Exposes an imperative instance API for @docsearch/js and @docsearch/sidepanel-js (open/close/destroy, plus state getters).
• Adds lifecycle callbacks (ready/open/close) for both modal and sidepanel.
• Wires this through @docsearch/core / @docsearch/react via forwarded refs + useImperativeHandle.

Motivation

Integrations (e.g. VitePress) currently resort to DOM polling to know when DocSearch/Sidepanel are ready and to open them programmatically. This adds a first-class programmatic API.

API changes

@docsearch/js

• docsearch(...) now returns a DocSearchInstance with:
  • open(), close(), openAskAi(), openSidepanel(), destroy()
  • isReady, isOpen, isSidepanelOpen
• New callbacks: onReady, onOpen, onClose, onSidepanelOpen, onSidepanelClose

@docsearch/sidepanel-js

• sidepanel(...) now returns a SidepanelInstance with:
  • open(), close(), openWithMessage(), destroy()
  • isReady, isOpen
• New callbacks: onReady, onOpen, onClose

BREAKING CHANGE

Yes: docsearch() and sidepanel() no longer return a bare cleanup function.

Migration:

// Before
const cleanup = docsearch(opts)
cleanup()

// After
const instance = docsearch(opts)
instance.destroy()

Tests

• Added unit coverage for the new imperative handle + lifecycle callbacks (packages/docsearch-react/src/__tests__/imperative.test.tsx).

[netlify]

❌ Deploy Preview for docsearch-demo failed.

Name	Link
🔨 Latest commit	04b054b
🔍 Latest deploy log	https://app.netlify.com/projects/docsearch-demo/deploys/695fdeda3216520008e272e1

[netlify]

✅ Deploy Preview for docsearch ready!

Name	Link
🔨 Latest commit	04b054b
🔍 Latest deploy log	https://app.netlify.com/projects/docsearch/deploys/695fdeda98cf180008bd2430
😎 Deploy Preview	https://deploy-preview-2826--docsearch.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 68a2151dd2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[8bittitan]

Could we add an example of this to examples/demo-js?