feat(adapter): add QueryBuilderAdapter for one-shot hydration and two-way binding

[cgarciagarcia]

Summary

• Adds QueryBuilderAdapter (read() + optional write(state)) on BaseConfig.adapter — bridges the builder to any external source (URL, localStorage, hash router, in-memory, …) with lazy one-shot read on creation and an opt-in per-mutation write for two-way binding.
• Adds the built-in createSearchParamsAdapter for the URL case (configurable keys for filter / sort / include / fields, explicit allowedParams allowlist, injectable source for SSR/tests).
• Exports the pure parseSearchParams helper for ad-hoc use without the adapter wrapper.
• Fixes a latent bug in useQueryBuilder where useRef(new Builder(config)) re-evaluated new Builder() on every render (only the first ref value was kept). The new lazy-ref pattern guarantees adapter.read() runs exactly once.
• Docs: new "Hydrating from URL" section in README.md, "Adapters" section in llms.txt, and two new live examples in docs/playground.html (URL Adapter and localStorage Adapter).
• Playground: adds an inline localStorage inspector that appears only when the localStorage Adapter tab is active — a textarea wired to the rqb-playground-demo key with Sample and Save & Run buttons, inline JSON validation, and auto-refresh after every Run (preserving focus so user edits aren't clobbered). Lets people drive the demo end-to-end without devtools.

API at a glance

// URL hydration with custom keys + extra params allowed
useQueryBuilder({
  adapter: createSearchParamsAdapter({
    keys: { filter: "filt", sort: "srt" },
    allowedParams: ["locale"],
  }),
})

// Custom adapter (e.g. localStorage two-way binding)
useQueryBuilder({
  adapter: {
    read:  () => JSON.parse(localStorage.getItem("qb") ?? "{}"),
    write: (state) => localStorage.setItem("qb", JSON.stringify(state)),
  },
})

Precedence on seed: defaults < adapter.read() < explicit BaseConfig fields — explicit config always wins.

Patterns used

• Adapter / Strategy for the read/write boundary — any source plugs in by implementing the interface.
• Lazy Initialization in the hook, matching useState(() => …) semantics.
• Dependency Inversion — the library no longer needs to import window; window.location.search lives inside the opt-in factory's default source.

Test plan

• pnpm test — 188/188 passing (3 new hook tests + dedicated suites for parser and adapter)
• pnpm lint — clean
• pnpm build:types — clean
• Manually open docs/playground.html and click URL Adapter → confirm the hydrated state appears in the right panel
• Manually open docs/playground.html, click localStorage Adapter, then Sample → Save & Run → confirm the builder hydrates from the textarea JSON
• Run code that mutates the builder and confirm the textarea auto-refreshes (unless focused) to reflect what write() persisted
• Smoke test in a consumer app: navigate to ?filt[status]=active&srt=-name&locale=es with the renamed keys and confirm builder.build() produces the canonical ?filter[status]=active&sort=-name&locale=es

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 71 complexity · 0 duplication

Metric	Results
Complexity	71
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}