Merge pull request #2 from react-querybuilder:idiomaticity-2

Refactor query builder state

Author: jakeboone02

AGENTS.md

@@ -185,7 +185,7 @@ setX(v)` returns the setter's return value and throws "invalid cleanup value". U
 - `createProjection(fn, seed, options?)` is a derived, **read-only** store with the same `'id'`
   default key. It can be driven from a non-reactive external source (the manager's subscribe
   callback) by bumping a version signal from that callback and reading the signal in `fn`; this is
-  what `createQueryBuilderState` uses.
+  what `createQueryBuilder` uses.
 - `createStore`'s setter takes a **draft callback** (`setStore(draft => { draft.x = … })`). There is
   no 1.x `setStore('key', value)` path-argument form; it throws `fn is not a function`.
 

CHANGELOG.md

@@ -16,6 +16,19 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **Breaking:** `createQueryBuilderState` is renamed **`createQueryBuilder`** and is now documented
+  as the package's headless entry point (see "Headless usage" in the README). It already was one —
+  it returns query, tree, manager, schema, actions and context and renders nothing — so this is a
+  naming change only. `CreateQueryBuilderStateOptions` is renamed `CreateQueryBuilderOptions`; the
+  returned `QueryBuilderState` interface keeps its name. No alias is kept.
+- **Breaking (source path only):** `createRuleActions` moved from `src/reactive/` to `src/actions.ts`.
+  It is the one module in the reactive layer with no reactive primitives — a pure `QueryManager` →
+  `QueryActions` adapter. The public barrel export is unchanged.
+- Internal: `createQueryBuilder.ts` (767 lines) is split along its existing `#region` seams into
+  `manager-options.ts` (the option builders and `valuesEqual`), `manager-bridge.ts` (manager
+  construction, query seeding, the version signals, the store projection, the subscription and the
+  three effects), `schema.ts` (the option lists, the resolvers and the `Schema` getter object) and
+  `context-value.ts`. Pure moves; the assembly file is ~200 lines and the new modules are internal.
 - Internal: ~20 `createMemo` calls that wrapped a single property read or a primitive-returning
   boolean expression are now plain closures. Solid props are already lazy getters, so those memos
   allocated a computation node to cache a property access. Memos that allocate an object, run a

README.md

@@ -85,6 +85,40 @@ function App() {
 }
 ```
 
+## Headless usage
+
+`createQueryBuilder` is the primitive `<QueryBuilder />` is built on, and it is public API. It takes
+the same props, returns the query, the manager, the schema, the actions and the context value, and
+renders nothing — so you can drive an entirely custom UI from it.
+
+```tsx
+import { For } from 'solid-js';
+import { createQueryBuilder } from 'solid-querybuilder';
+
+function CustomBuilder(props) {
+  const state = createQueryBuilder(props);
+
+  return (
+    <ul>
+      <For each={state.rootGroup.rules}>
+        {(r, i) => (
+          <li>
+            {r.field} {r.operator} {String(r.value)}
+            <button onClick={() => state.actions.onRuleRemove([i()])}>×</button>
+          </li>
+        )}
+      </For>
+      <button onClick={() => state.actions.onRuleAdd(state.schema.createRule(), [])}>+ rule</button>
+    </ul>
+  );
+}
+```
+
+Read the query from `state.rootGroup` (the store mirror, reconciled by `id`, so `<For>` sees stable
+identities) rather than `state.query` (a plain identity signal) whenever you are rendering it.
+`state.manager` is the underlying [`QueryManager`](https://react-querybuilder.js.org); everything
+else is derived from it.
+
 ## Styling
 
 Two prebuilt stylesheets ship in `dist`: `query-builder.css` (full) and

docs/differences-from-react-querybuilder.md

@@ -144,8 +144,9 @@ signature — so no component needs a `widenedProps` re-widening cast.
 
 React Query Builder's hooks (`useQueryBuilder`, `useRule`, `useRuleGroup`, `useValueEditor`, …) are
 not ported under those names. The Solid equivalents live in the `reactive/` layer and are exported:
-`createQueryBuilderState`, `createRuleState`, `createRuleGroupState`, `createRuleActions`,
-`createValueEditorReset`, and the `QueryBuilderContext` / `useQueryBuilderConfig` pair. The `create*`
+`createQueryBuilder`, `createRuleState`, `createRuleGroupState`, `createValueEditorReset`, and the
+`QueryBuilderContext` / `useQueryBuilderConfig` pair (`createRuleActions` is exported too, from
+`src/actions.ts` — it uses no reactive primitives). The `create*`
 naming disambiguates from core's own `createRule` / `createRuleGroup` / `createQueryActions`, which
 this package re-exports.
 

…r/src/reactive/createRuleActions.test.ts …s/solid-querybuilder/src/actions.test.tspackages/solid-querybuilder/src/reactive/createRuleActions.test.ts renamed to packages/solid-querybuilder/src/actions.test.ts packages/solid-querybuilder/src/reactive/createRuleActions.test.ts renamed to packages/solid-querybuilder/src/actions.test.ts

@@ -2,9 +2,9 @@ import type { RuleGroupType, RuleType } from '@react-querybuilder/core';
 import { QueryManager } from '@react-querybuilder/core';
 import { createStore } from 'solid-js';
 import { describe, expect, it, vi } from 'vitest';
-import { flatQuery, testFields } from '../../test/support.js';
-import type { QueryBuilderProps } from '../types/props.js';
-import { createRuleActions } from './createRuleActions.js';
+import { flatQuery, testFields } from '../test/support.js';
+import { createRuleActions } from './actions.js';
+import type { QueryBuilderProps } from './types/props.js';
 
 const nested: RuleGroupType = {
   id: 'root',

…uilder/src/reactive/createRuleActions.ts …ckages/solid-querybuilder/src/actions.tspackages/solid-querybuilder/src/reactive/createRuleActions.ts renamed to packages/solid-querybuilder/src/actions.ts packages/solid-querybuilder/src/reactive/createRuleActions.ts renamed to packages/solid-querybuilder/src/actions.ts

@@ -10,7 +10,7 @@ import type {
 } from '@react-querybuilder/core';
 import { isRuleGroup } from '@react-querybuilder/core';
 import { snapshot } from 'solid-js';
-import type { QueryBuilderProps } from '../types/props.js';
+import type { QueryBuilderProps } from './types/props.js';
 
 /**
  * The `onAdd*`/`onMove*`/`onGroup*`/`onRemove` props return `false` to cancel an operation, a

packages/solid-querybuilder/src/components/QueryBuilder.tsx

@@ -9,15 +9,15 @@ import { rootPath } from '@react-querybuilder/core';
 import type { JSX } from '@solidjs/web';
 import { Dynamic } from '@solidjs/web';
 import { QueryBuilderContext } from '../reactive/context.js';
-import { createQueryBuilderState } from '../reactive/createQueryBuilderState.js';
+import { createQueryBuilder } from '../reactive/createQueryBuilder.js';
 import type { QueryBuilderProps } from '../types/props.js';
 import { defaultControlElements } from './defaultControlElements.js';
 
 /**
  * The query builder.
  *
  * Port of React Query Builder's `QueryBuilder`/`QueryBuilderInternal`. All state lives in a
- * `QueryManager`; see `createQueryBuilderState`. The query can be driven three ways:
+ * `QueryManager`; see `createQueryBuilder`. The query can be driven three ways:
  *
  * - `query` + `onQueryChange` — controlled.
  * - `defaultQuery` — uncontrolled.
@@ -38,7 +38,7 @@ export const QueryBuilder = <
   // read through for the lifetime of the component.
   const p = props as QueryBuilderProps<RuleGroupTypeAny, F, O, FullCombinator>;
 
-  const state = createQueryBuilderState<F, O>(p, { defaultControls: defaultControlElements });
+  const state = createQueryBuilder<F, O>(p, { defaultControls: defaultControlElements });
 
   return (
     // Solid 2 removed `.Provider`. `state.context` is a getter object, so descendants read

packages/solid-querybuilder/src/components/Rule.tsx

@@ -11,7 +11,7 @@ import type { RuleProps } from '../types/props.js';
  *
  * Port of React Query Builder's `Rule`, and, like it, a small wrapper: the controls themselves
  * live in `RuleComponents`, and a rule whose field supports match modes renders `RuleSubQuery`
- * instead — which needs its own `createQueryBuilderState`, and therefore its own component.
+ * instead — which needs its own `createQueryBuilder`, and therefore its own component.
  *
  * Element order and conditional rendering are the contract: read React's `Rule.tsx` as the spec.
  */

packages/solid-querybuilder/src/index.tsx

@@ -7,6 +7,7 @@
 // This is a star export, so it loses every name the port declares explicitly below; that is the
 // intended precedence (the port's `Schema`, `RuleProps`, etc. are deliberate deltas).
 export * from '@react-querybuilder/core';
+export * from './actions.js';
 export * from './components/index.js';
 export { Label } from './internal/Label.jsx';
 export * from './reactive/index.js';

packages/solid-querybuilder/src/internal/RuleSubQuery.tsx

@@ -3,7 +3,7 @@ import { isRuleGroup, prepareOptionList, rootPath } from '@react-querybuilder/co
 import type { JSX } from '@solidjs/web';
 import { createMemo, merge, untrack } from 'solid-js';
 import { defaultControlElements } from '../components/defaultControlElements.js';
-import { createQueryBuilderState } from '../reactive/createQueryBuilderState.js';
+import { createQueryBuilder } from '../reactive/createQueryBuilder.js';
 import { createRuleGroupState } from '../reactive/createRuleGroupState.js';
 import type { RuleState } from '../reactive/createRuleState.js';
 import type { QueryBuilderProps, RuleGroupProps, RuleProps } from '../types/props.js';
@@ -16,7 +16,7 @@ const defaultSubproperties: FullField[] = [{ name: '', value: '', label: '' }];
  * builder for the rule's value.
  *
  * Port of React Query Builder's `RuleComponentsWithSubQuery`. It exists as its own component for
- * the same reason React's does: the subquery needs its own `createQueryBuilderState`, which runs
+ * the same reason React's does: the subquery needs its own `createQueryBuilder`, which runs
  * during component setup and therefore cannot live behind a `<Show>` inside `Rule`.
  *
  * It provides no new context, matching React and both prior ports — a replacement control
@@ -71,7 +71,7 @@ export const RuleSubQuery = (props: { ruleProps: RuleProps; parts: RuleState }):
     },
   }) as unknown as QueryBuilderProps<RuleGroupTypeAny>;
 
-  const subState = createQueryBuilderState(() => subProps as never, {
+  const subState = createQueryBuilder(() => subProps as never, {
     defaultControls: defaultControlElements as never,
   });