feat: Added query text editor

- SQL text editor
- Optional monaco editor to support more advanced use cases
- text editor validation
- Updated website
- Updated readme

Author: Vojtěch Václav Porteš

README.md

@@ -25,6 +25,10 @@ React Query Builder is a TypeScript library for building nested filter editors,
 formatting them into external query syntaxes, and parsing supported expressions
 back into builder state.
 
+It also supports an optional SQL text mode for `Builder`, with built-in syntax
+and semantic validation, plus an optional Monaco-based advanced editor
+integration for protected locked ranges.
+
 Full documentation, API reference, and the interactive demo are available on
 the project website:
 
@@ -164,6 +168,30 @@ export const MyBuilder = () => {
 };
 ```
 
+## Text Mode
+
+`Builder` can optionally switch between the visual query UI and a SQL text
+editor view.
+
+```tsx
+<Builder
+  fields={fields}
+  data={data}
+  textMode
+  defaultMode="text"
+  onChange={setData}
+/>;
+```
+
+For advanced text editing, the package also exposes
+`@vojtechportes/react-query-builder/monaco`. The built-in editor is lightweight
+and works without extra dependencies, while the Monaco integration is the
+recommended path when locked query segments must stay protected in text mode.
+
+- <a href="https://vojtechportes.github.io/react-query-builder/documentation/text-mode" target="_blank" rel="noopener noreferrer">Documentation: Text Mode</a>
+- <a href="https://vojtechportes.github.io/react-query-builder/api/builder" target="_blank" rel="noopener noreferrer">API: Builder</a>
+- <a href="https://vojtechportes.github.io/react-query-builder/api/components" target="_blank" rel="noopener noreferrer">API: Components</a>
+
 ## Query Conversion
 
 The library also provides parser and formatter helpers through subpath exports:

example/src/app/app.tsx

@@ -53,6 +53,7 @@ export const App: React.FC = () => (
           <Route path="/documentation/validation" element={<DocumentationPage />} />
           <Route path="/documentation/history" element={<DocumentationPage />} />
           <Route path="/documentation/builder-behavior" element={<DocumentationPage />} />
+          <Route path="/documentation/text-mode" element={<DocumentationPage />} />
           <Route
             path="/documentation/locking-and-read-only"
             element={<DocumentationPage />}

example/src/components/demo-playground.tsx

@@ -5,6 +5,7 @@ import {
   type DenormalizedQuery,
 } from '@vojtechportes/react-query-builder';
 import { components as antdComponents } from '@vojtechportes/react-query-builder/antd/v6';
+import { createMonacoComponents } from '@vojtechportes/react-query-builder/monaco';
 import { components as muiComponents } from '@vojtechportes/react-query-builder/mui/v9';
 import type { IColors } from '../../../src/constants/colors';
 import { ThemeProvider } from '../../../src/theme-provider/theme-provider';
@@ -54,17 +55,26 @@ const PanelTitle = styled.h3`
   color: #0f172a;
 `;
 
-const ToggleRow = styled.label`
+const ToggleRow = styled.label<{ $disabled?: boolean }>`
   display: flex;
   align-items: center;
   gap: 0.75rem;
   font-size: 0.95rem;
   color: #334155;
+  cursor: ${({ $disabled }) => ($disabled ? 'not-allowed' : 'pointer')};
 `;
 
-const Toggle = styled.input`
+const Toggle = styled.input<{ $disabled?: boolean }>`
   width: 18px;
   height: 18px;
+  margin: 0;
+  accent-color: #2563eb;
+  cursor: ${({ $disabled }) => ($disabled ? 'not-allowed' : 'pointer')};
+  flex: 0 0 18px;
+
+  &:disabled {
+    opacity: 1;
+  }
 `;
 
 const ChoiceGroup = styled.div`
@@ -152,6 +162,9 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
   const [cloneable, setCloneable] = React.useState(false);
   const [draggable, setDraggable] = React.useState(false);
   const [history, setHistory] = React.useState(false);
+  const [textMode, setTextMode] = React.useState(false);
+  const [defaultMode, setDefaultMode] = React.useState<'builder' | 'text'>('builder');
+  const [useMonacoTextEditor, setUseMonacoTextEditor] = React.useState(false);
   const [singleRootGroup, setSingleRootGroup] = React.useState(true);
   const [showValidation, setShowValidation] = React.useState(true);
   const [customizationMode, setCustomizationMode] =
@@ -164,6 +177,27 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
   const isAntdMode = customizationMode === 'antd';
   const usesAdapterMode = isMuiMode || isAntdMode;
 
+  React.useEffect(() => {
+    if (!singleRootGroup && textMode) {
+      setTextMode(false);
+    }
+  }, [singleRootGroup, textMode]);
+
+  const builderComponents = React.useMemo(() => {
+    const baseComponents =
+      customizationMode === 'mui'
+        ? muiComponents
+        : customizationMode === 'antd'
+          ? antdComponents
+          : undefined;
+
+    if (!useMonacoTextEditor) {
+      return baseComponents;
+    }
+
+    return createMonacoComponents(baseComponents || {});
+  }, [customizationMode, useMonacoTextEditor]);
+
   const builderProps = {
     data,
     fields: demoFields,
@@ -173,9 +207,12 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
     onChange: setData,
     draggable,
     history,
+    textMode,
+    defaultMode,
     groupTypes: 'both' as const,
     singleRootGroup,
     showValidation,
+    ...(builderComponents ? { components: builderComponents } : {}),
   };
 
   const outputText = React.useMemo(() => {
@@ -194,6 +231,9 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
         cloneable,
         draggable,
         history,
+        textMode,
+        defaultMode,
+        useMonacoTextEditor,
         singleRootGroup,
         showValidation,
         customizationMode,
@@ -206,6 +246,9 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
       cloneable,
       draggable,
       history,
+      textMode,
+      defaultMode,
+      useMonacoTextEditor,
       singleRootGroup,
       showValidation,
       customizationMode,
@@ -264,6 +307,50 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
             <span>Undo / redo history</span>
           </ToggleRow>
 
+          <ToggleRow $disabled={!singleRootGroup}>
+            <Toggle
+              type="checkbox"
+              checked={textMode}
+              disabled={!singleRootGroup}
+              $disabled={!singleRootGroup}
+              onChange={event => setTextMode(event.target.checked)}
+            />
+            <span>
+              Text editor mode
+              {!singleRootGroup ? ' (requires single root group)' : ''}
+            </span>
+          </ToggleRow>
+
+          <ToggleRow $disabled={!textMode}>
+            <Toggle
+              type="checkbox"
+              checked={defaultMode === 'text'}
+              disabled={!textMode}
+              $disabled={!textMode}
+              onChange={event =>
+                setDefaultMode(event.target.checked ? 'text' : 'builder')
+              }
+            />
+            <span>
+              Open in text mode
+              {!textMode ? ' (requires text editor mode)' : ''}
+            </span>
+          </ToggleRow>
+
+          <ToggleRow $disabled={!textMode}>
+            <Toggle
+              type="checkbox"
+              checked={useMonacoTextEditor}
+              disabled={!textMode}
+              $disabled={!textMode}
+              onChange={event => setUseMonacoTextEditor(event.target.checked)}
+            />
+            <span>
+              Monaco text editor
+              {!textMode ? ' (requires text editor mode)' : ''}
+            </span>
+          </ToggleRow>
+
           <ToggleRow>
             <Toggle
               type="checkbox"
@@ -355,15 +442,9 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
         <BuilderCard>
           <BuilderSurface>
             {isMuiMode ? (
-              <Builder
-                {...builderProps}
-                components={muiComponents}
-              />
+              <Builder {...builderProps} />
             ) : isAntdMode ? (
-              <Builder
-                {...builderProps}
-                components={antdComponents}
-              />
+              <Builder {...builderProps} />
             ) : (
               <ThemeProvider colors={themeColors}>
                 <Builder {...builderProps} />

example/src/components/theme-editor.tsx

@@ -76,6 +76,14 @@ type ColorPath =
   | 'grey.700'
   | 'grey.800'
   | 'grey.900'
+  | 'info.primary'
+  | 'info.light'
+  | 'success.primary'
+  | 'success.light'
+  | 'warning.primary'
+  | 'warning.light'
+  | 'error.primary'
+  | 'error.light'
   | 'white';
 
 const controls: { label: string; name: ColorPath }[] = [
@@ -96,6 +104,14 @@ const controls: { label: string; name: ColorPath }[] = [
   { label: 'Grey 700', name: 'grey.700' },
   { label: 'Grey 800', name: 'grey.800' },
   { label: 'Grey 900', name: 'grey.900' },
+  { label: 'Info primary', name: 'info.primary' },
+  { label: 'Info light', name: 'info.light' },
+  { label: 'Success primary', name: 'success.primary' },
+  { label: 'Success light', name: 'success.light' },
+  { label: 'Warning primary', name: 'warning.primary' },
+  { label: 'Warning light', name: 'warning.light' },
+  { label: 'Error primary', name: 'error.primary' },
+  { label: 'Error light', name: 'error.light' },
   { label: 'White', name: 'white' },
 ];
 
@@ -104,7 +120,18 @@ const getColorValue = (themeColors: IColors, path: ColorPath) => {
     return themeColors.white;
   }
 
-  const [group, key] = path.split('.') as [
+  const keys = path.split('.');
+
+  if (keys[0] === 'info' || keys[0] === 'success' || keys[0] === 'warning' || keys[0] === 'error') {
+    const [group, key] = keys as [
+      keyof Pick<IColors, 'info' | 'success' | 'warning' | 'error'>,
+      keyof IColors['info'],
+    ];
+
+    return themeColors[group][key];
+  }
+
+  const [group, key] = keys as [
     'primary' | 'secondary' | 'grey',
     keyof IColors['primary'] & keyof IColors['grey'],
   ];
@@ -121,7 +148,24 @@ const setColorValue = (
     return { ...themeColors, white: nextValue };
   }
 
-  const [group, key] = path.split('.') as [
+  const keys = path.split('.');
+
+  if (keys[0] === 'info' || keys[0] === 'success' || keys[0] === 'warning' || keys[0] === 'error') {
+    const [group, key] = keys as [
+      keyof Pick<IColors, 'info' | 'success' | 'warning' | 'error'>,
+      keyof IColors['info'],
+    ];
+
+    return {
+      ...themeColors,
+      [group]: {
+        ...themeColors[group],
+        [key]: nextValue,
+      },
+    };
+  }
+
+  const [group, key] = keys as [
     'primary' | 'secondary' | 'grey',
     keyof IColors['primary'] & keyof IColors['grey'],
   ];