@shipfox/react-ui 0.32.2 → 0.33.1

package/dist/components/shipql-editor/lexical/shipql-plugin.js

@@ -1,9 +1,9 @@
 import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
 import { parse, removeBySource, stringify } from '@shipfox/shipql-parser';
-import { $createRangeSelection, $createTextNode, $getRoot, $getSelection, $isRangeSelection, $isTextNode, $setSelection, COMMAND_PRIORITY_HIGH, COMMAND_PRIORITY_NORMAL, createCommand, INSERT_PARAGRAPH_COMMAND, KEY_ARROW_RIGHT_COMMAND, KEY_ENTER_COMMAND } from 'lexical';
+import { $createRangeSelection, $createTextNode, $getRoot, $getSelection, $isRangeSelection, $isTextNode, $setSelection, BLUR_COMMAND, COMMAND_PRIORITY_HIGH, COMMAND_PRIORITY_LOW, COMMAND_PRIORITY_NORMAL, createCommand, FOCUS_COMMAND, INSERT_PARAGRAPH_COMMAND, KEY_ARROW_RIGHT_COMMAND, KEY_ENTER_COMMAND } from 'lexical';
 import { useEffect, useRef } from 'react';
 import { handleArrowRightFromLeaf } from './handle-arrow-right-from-leaf.js';
-import { $createShipQLLeafNode, $isShipQLLeafNode, isGroupedCompound, isSimpleLeaf, leafSource } from './shipql-leaf-node.js';
+import { $createShipQLLeafNode, $isShipQLLeafNode, $setLeafFreeTextError, isGroupedCompound, isSimpleLeaf, leafSource } from './shipql-leaf-node.js';
 function collectLeaves(ast) {
     // Simple terminals are always a single leaf chip.
     if (isSimpleLeaf(ast)) {
@@ -86,7 +86,15 @@ function needsRebuild(children, segments) {
     }
     return false;
 }
+function getOrderedLeafStateKey(text, counts) {
+    const index = (counts.get(text) ?? 0) + 1;
+    counts.set(text, index);
+    return `${text}::${index}`;
+}
 function getAbsoluteOffset(para, point) {
+    if (point.type === 'element') {
+        return para.getChildren().slice(0, point.offset).reduce((offset, child)=>offset + ($isTextNode(child) ? child.getTextContentSize() : 0), 0);
+    }
     let offset = 0;
     for (const child of para.getChildren()){
         if (child.getKey() === point.key) return offset + point.offset;
@@ -94,19 +102,62 @@ function getAbsoluteOffset(para, point) {
     }
     return offset + point.offset;
 }
+function getDesiredLeafErrorState(segments, selectionOffset, allowFreeText, isFocused) {
+    const counts = new Map();
+    const leafRanges = [];
+    let offset = 0;
+    for (const seg of segments){
+        if (seg.kind === 'leaf') {
+            leafRanges.push({
+                stateKey: getOrderedLeafStateKey(seg.text, counts),
+                node: seg.node,
+                start: offset,
+                end: offset + seg.text.length
+            });
+        }
+        offset += seg.text.length;
+    }
+    const activeLeafKey = selectionOffset >= 0 ? leafRanges.find((leaf)=>selectionOffset >= leaf.start && selectionOffset <= leaf.end)?.stateKey ?? null : null;
+    const errorState = new Map();
+    for (const leaf of leafRanges){
+        const shouldError = !allowFreeText && isTextLeaf(leaf.node) && (!isFocused || leaf.stateKey !== activeLeafKey);
+        errorState.set(leaf.stateKey, shouldError);
+    }
+    return errorState;
+}
+function leafErrorStateMatches(children, desiredErrorState) {
+    const counts = new Map();
+    for (const child of children){
+        if (!$isShipQLLeafNode(child)) continue;
+        const stateKey = getOrderedLeafStateKey(child.getTextContent(), counts);
+        if ((desiredErrorState.get(stateKey) ?? false) !== child.getLatest().__freeTextError) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Returns true if a leaf segment represents a free-text node (bare word / quoted string). */ function isTextLeaf(node) {
+    if (node.type === 'text') return true;
+    if (node.type === 'not' && node.expr.type === 'text') return true;
+    return false;
+}
 // ─── Commands ─────────────────────────────────────────────────────────────────
 /** Payload: the Lexical node key of the leaf to remove. */ export const REMOVE_LEAF_COMMAND = createCommand('REMOVE_LEAF_COMMAND');
 // ─── Plugin ───────────────────────────────────────────────────────────────────
 const REBUILD_TAG = 'shipql-rebuild';
-export function ShipQLPlugin({ onLeafFocus, formatLeafDisplay }) {
+export function ShipQLPlugin({ onLeafFocus, formatLeafDisplay, allowFreeText = true }) {
     const [editor] = useLexicalComposerContext();
     // Keep latest callback accessible inside Lexical listeners without re-registering.
     const onLeafFocusRef = useRef(onLeafFocus);
     onLeafFocusRef.current = onLeafFocus;
     const formatLeafDisplayRef = useRef(formatLeafDisplay);
     formatLeafDisplayRef.current = formatLeafDisplay;
+    const allowFreeTextRef = useRef(allowFreeText);
+    allowFreeTextRef.current = allowFreeText;
     // Track the key of the last focused leaf to avoid redundant callbacks.
     const lastFocusedKeyRef = useRef(null);
+    // Track whether the editor is focused so we can show errors only when blurred.
+    const isFocusedRef = useRef(true);
     useEffect(()=>{
         // Block newlines — ShipQL is a single-line language.
         const unregisterEnter = editor.registerCommand(KEY_ENTER_COMMAND, (event)=>{
@@ -156,6 +207,85 @@ export function ShipQLPlugin({ onLeafFocus, formatLeafDisplay }) {
             });
             return true;
         }, COMMAND_PRIORITY_HIGH);
+        // ── Blur / Focus: toggle free-text error styling via rebuild ────────────
+        function syncLeafNodesWithCurrentState() {
+            editor.update(()=>{
+                const para = $getRoot().getFirstChild();
+                if (!para) return;
+                const text = para.getTextContent();
+                const children = para.getChildren();
+                const sel = $getSelection();
+                const selectionOffset = $isRangeSelection(sel) ? getAbsoluteOffset(para, sel.anchor) : -1;
+                if (!text) {
+                    if (children.some($isShipQLLeafNode)) {
+                        para.clear();
+                    }
+                    return;
+                }
+                let ast = null;
+                try {
+                    ast = parse(text);
+                } catch  {
+                    return;
+                }
+                if (!ast) {
+                    if (!children.some($isShipQLLeafNode)) return;
+                    para.clear();
+                    para.append($createTextNode(text));
+                    return;
+                }
+                const segments = tokenize(text, collectLeaves(ast));
+                const fmt = formatLeafDisplayRef.current;
+                const desiredLeafErrors = getDesiredLeafErrorState(segments, selectionOffset, allowFreeTextRef.current, isFocusedRef.current);
+                if (!needsRebuild(children, segments) && leafErrorStateMatches(children, desiredLeafErrors)) {
+                    return;
+                }
+                para.clear();
+                const newNodes = [];
+                const counts = new Map();
+                for (const seg of segments){
+                    const node = seg.kind === 'leaf' ? $createShipQLLeafNode(seg.text, seg.node, fmt?.(seg.text, seg.node), desiredLeafErrors.get(getOrderedLeafStateKey(seg.text, counts)) ?? false) : $createTextNode(seg.text);
+                    newNodes.push(node);
+                    para.append(node);
+                }
+                if (selectionOffset >= 0 && newNodes.length > 0) {
+                    let remaining = selectionOffset;
+                    let lastTextNode = null;
+                    for (const node of newNodes){
+                        if (!$isTextNode(node)) continue;
+                        lastTextNode = node;
+                        const len = node.getTextContentSize();
+                        if (remaining <= len) {
+                            const nextSelection = $createRangeSelection();
+                            nextSelection.anchor.set(node.getKey(), remaining, 'text');
+                            nextSelection.focus.set(node.getKey(), remaining, 'text');
+                            $setSelection(nextSelection);
+                            return;
+                        }
+                        remaining -= len;
+                    }
+                    if (lastTextNode && $isTextNode(lastTextNode)) {
+                        const endSelection = $createRangeSelection();
+                        const end = lastTextNode.getTextContentSize();
+                        endSelection.anchor.set(lastTextNode.getKey(), end, 'text');
+                        endSelection.focus.set(lastTextNode.getKey(), end, 'text');
+                        $setSelection(endSelection);
+                    }
+                }
+            }, {
+                tag: REBUILD_TAG
+            });
+        }
+        const unregisterBlur = editor.registerCommand(BLUR_COMMAND, ()=>{
+            isFocusedRef.current = false;
+            if (!allowFreeTextRef.current) syncLeafNodesWithCurrentState();
+            return false;
+        }, COMMAND_PRIORITY_LOW);
+        const unregisterFocus = editor.registerCommand(FOCUS_COMMAND, ()=>{
+            isFocusedRef.current = true;
+            if (!allowFreeTextRef.current) syncLeafNodesWithCurrentState();
+            return false;
+        }, COMMAND_PRIORITY_LOW);
         const unregisterUpdate = editor.registerUpdateListener(({ editorState, tags })=>{
             // After our own rebuild we only need to refresh the leaf-focus callback.
             if (tags.has(REBUILD_TAG)) {
@@ -175,6 +305,8 @@ export function ShipQLPlugin({ onLeafFocus, formatLeafDisplay }) {
             let shouldRebuild = false;
             let nextSegments = [];
             let savedOffset = -1;
+            let desiredLeafErrors = new Map();
+            let needsErrorStateUpdate = false;
             editorState.read(()=>{
                 const para = $getRoot().getFirstChild();
                 if (!para) return;
@@ -197,7 +329,7 @@ export function ShipQLPlugin({ onLeafFocus, formatLeafDisplay }) {
                             }
                         ] : [];
                         const sel = $getSelection();
-                        if ($isRangeSelection(sel) && sel.anchor.type === 'text') {
+                        if ($isRangeSelection(sel)) {
                             savedOffset = getAbsoluteOffset(para, sel.anchor);
                         }
                     }
@@ -209,16 +341,16 @@ export function ShipQLPlugin({ onLeafFocus, formatLeafDisplay }) {
                     return;
                 }
                 const segments = tokenize(text, collectLeaves(ast));
+                const sel = $getSelection();
+                if ($isRangeSelection(sel)) {
+                    savedOffset = getAbsoluteOffset(para, sel.anchor);
+                }
+                desiredLeafErrors = getDesiredLeafErrorState(segments, savedOffset, allowFreeTextRef.current, isFocusedRef.current);
                 if (needsRebuild(children, segments)) {
                     shouldRebuild = true;
                     nextSegments = segments;
-                    const sel = $getSelection();
-                    if ($isRangeSelection(sel) && sel.anchor.type === 'text') {
-                        savedOffset = getAbsoluteOffset(para, sel.anchor);
-                    }
                 } else {
-                    // No structural change — just update leaf-focus.
-                    const sel = $getSelection();
+                    // No structural change — update leaf-focus and deferred text-node errors.
                     if ($isRangeSelection(sel)) {
                         const anchor = sel.anchor.getNode();
                         const key = $isShipQLLeafNode(anchor) ? anchor.getKey() : null;
@@ -226,32 +358,72 @@ export function ShipQLPlugin({ onLeafFocus, formatLeafDisplay }) {
                             lastFocusedKeyRef.current = key;
                             onLeafFocusRef.current?.(key !== null && $isShipQLLeafNode(anchor) ? anchor.getShipQLNode() : null);
                         }
+                    } else if (lastFocusedKeyRef.current !== null) {
+                        lastFocusedKeyRef.current = null;
+                        onLeafFocusRef.current?.(null);
                     }
+                    needsErrorStateUpdate = !leafErrorStateMatches(children, desiredLeafErrors);
                 }
             });
-            if (!shouldRebuild) return;
+            if (!shouldRebuild) {
+                if (needsErrorStateUpdate) {
+                    editor.update(()=>{
+                        const para = $getRoot().getFirstChild();
+                        if (!para) return;
+                        const counts = new Map();
+                        for (const child of para.getChildren()){
+                            if (!$isShipQLLeafNode(child)) continue;
+                            const stateKey = getOrderedLeafStateKey(child.getTextContent(), counts);
+                            $setLeafFreeTextError(child, desiredLeafErrors.get(stateKey) ?? false);
+                        }
+                    }, {
+                        tag: REBUILD_TAG
+                    });
+                }
+                return;
+            }
             // ── Rebuild node structure ─────────────────────────────────────────────
             editor.update(()=>{
                 const para = $getRoot().getFirstChild();
                 if (!para) return;
                 para.clear();
                 const fmt = formatLeafDisplayRef.current;
-                const newNodes = nextSegments.map((seg)=>seg.kind === 'leaf' ? $createShipQLLeafNode(seg.text, seg.node, fmt?.(seg.text, seg.node)) : $createTextNode(seg.text));
+                const occurrenceCounts = new Map();
+                const newNodes = nextSegments.map((seg)=>{
+                    if (seg.kind === 'leaf') {
+                        const stateKey = getOrderedLeafStateKey(seg.text, occurrenceCounts);
+                        const freeTextError = desiredLeafErrors.get(stateKey) ?? false;
+                        return $createShipQLLeafNode(seg.text, seg.node, fmt?.(seg.text, seg.node), freeTextError);
+                    }
+                    return $createTextNode(seg.text);
+                });
                 for (const node of newNodes)para.append(node);
                 // Restore cursor to the same absolute character position.
                 if (savedOffset >= 0 && newNodes.length > 0) {
                     let remaining = savedOffset;
+                    let lastTextNode = null;
+                    let restoredSelection = false;
                     for (const node of newNodes){
-                        const len = $isTextNode(node) ? node.getTextContentSize() : 0;
+                        if (!$isTextNode(node)) continue;
+                        lastTextNode = node;
+                        const len = node.getTextContentSize();
                         if (remaining <= len) {
                             const sel = $createRangeSelection();
                             sel.anchor.set(node.getKey(), remaining, 'text');
                             sel.focus.set(node.getKey(), remaining, 'text');
                             $setSelection(sel);
+                            restoredSelection = true;
                             break;
                         }
                         remaining -= len;
                     }
+                    if (!restoredSelection && lastTextNode && $isTextNode(lastTextNode)) {
+                        const sel = $createRangeSelection();
+                        const end = lastTextNode.getTextContentSize();
+                        sel.anchor.set(lastTextNode.getKey(), end, 'text');
+                        sel.focus.set(lastTextNode.getKey(), end, 'text');
+                        $setSelection(sel);
+                    }
                 }
             }, {
                 tag: REBUILD_TAG
@@ -261,32 +433,14 @@ export function ShipQLPlugin({ onLeafFocus, formatLeafDisplay }) {
         // registered after Lexical has already committed its initialConfig editorState
         // (useEffect runs post-paint), so the listener never fires for the first render.
         // We do the full rebuild here instead of relying on the listener being triggered.
-        editor.update(()=>{
-            const para = $getRoot().getFirstChild();
-            if (!para) return;
-            const text = para.getTextContent();
-            if (!text) return;
-            const children = para.getChildren();
-            let ast = null;
-            try {
-                ast = parse(text);
-            } catch  {
-                return;
-            }
-            if (!ast) return;
-            const segments = tokenize(text, collectLeaves(ast));
-            if (!needsRebuild(children, segments)) return;
-            const fmt = formatLeafDisplayRef.current;
-            para.clear();
-            for (const seg of segments){
-                para.append(seg.kind === 'leaf' ? $createShipQLLeafNode(seg.text, seg.node, fmt?.(seg.text, seg.node)) : $createTextNode(seg.text));
-            }
-        });
+        syncLeafNodesWithCurrentState();
         return ()=>{
             unregisterEnter();
             unregisterParagraph();
             unregisterArrowRight();
             unregisterRemoveLeaf();
+            unregisterBlur();
+            unregisterFocus();
             unregisterUpdate();
         };
     }, [

package/dist/components/shipql-editor/shipql-editor-inner.d.ts

@@ -1,3 +1,3 @@
-import type { ShipQLEditorInnerProps } from './shipql-editor';
-export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder, className, disabled, mode, text, editorKey, isError, onTextChange, onClear, onToggleMode, facets, currentFacet, setCurrentFacet, valueSuggestions, isLoadingValueSuggestions, onLeafChange, formatLeafDisplay, }: ShipQLEditorInnerProps): import("react/jsx-runtime").JSX.Element;
+import type { ShipQLEditorInnerProps } from './shipql-editor.js';
+export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder, className, disabled, mode, text, editorKey, isError, onTextChange, onClear, onToggleMode, facets, currentFacet, setCurrentFacet, valueSuggestions, isLoadingValueSuggestions, onLeafChange, formatLeafDisplay, allowFreeText, }: ShipQLEditorInnerProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=shipql-editor-inner.d.ts.map

package/dist/components/shipql-editor/shipql-editor-inner.js

@@ -4,10 +4,11 @@ import { ContentEditable } from '@lexical/react/LexicalContentEditable';
 import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
 import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
 import { PlainTextPlugin } from '@lexical/react/LexicalPlainTextPlugin';
+import { hasTextNodes } from '@shipfox/shipql-parser';
 import { Input } from '../../components/input/index.js';
 import { Popover, PopoverAnchor } from '../../components/popover/index.js';
 import { $createParagraphNode, $createTextNode, $getRoot } from 'lexical';
-import { useCallback, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { cn } from '../../utils/cn.js';
 import { Icon } from '../icon/icon.js';
 import { LeafCloseOverlay } from './lexical/leaf-close-overlay.js';
@@ -21,16 +22,19 @@ import { ShipQLSuggestionsPlugin } from './suggestions/shipql-suggestions-plugin
 const INPUT_CLASSES = 'block w-full rounded-6 bg-background-field-base py-2 pl-32 pr-58 sm:pr-64 text-md text-foreground-neutral-base caret-foreground-neutral-base outline-none focus:border-border-highlights-interactive shadow-button-neutral';
 const INPUT_ERROR_CLASSES = 'shadow-border-error';
 const BUTTON_CLASSES = 'shrink-0 text-foreground-neutral-subtle hover:text-foreground-neutral-base transition-all duration-150 flex justify-center items-center cursor-pointer w-28 sm:w-32 h-full';
-export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder, className, disabled, mode, text, editorKey, isError, onTextChange, onClear, onToggleMode, facets, currentFacet, setCurrentFacet, valueSuggestions, isLoadingValueSuggestions, onLeafChange, formatLeafDisplay }) {
+export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder, className, disabled, mode, text, editorKey, isError, onTextChange, onClear, onToggleMode, facets, currentFacet, setCurrentFacet, valueSuggestions, isLoadingValueSuggestions, onLeafChange, formatLeafDisplay, allowFreeText }) {
     const [suggestionsOpen, setSuggestionsOpen] = useState(false);
     const [selectedIndex, setSelectedIndex] = useState(-1);
     const [items, setItems] = useState([]);
     const [focusedLeafNode, setFocusedLeafNode] = useState(null);
     const [isNegated, setIsNegated] = useState(false);
     const [showSyntaxHelp, setShowSyntaxHelp] = useState(false);
+    const [isTextModeBlurError, setIsTextModeBlurError] = useState(false);
     const isSelectingRef = useRef(false);
     const applyRef = useRef(null);
     const negationPrefixRef = useRef('');
+    const containerRef = useRef(null);
+    const suggestionsSuppressedRef = useRef(false);
     const hasSuggestions = Boolean(facets && facets.length > 0);
     const showValueActions = Boolean(currentFacet);
     const isRangeContext = items.length === 1 && items[0]?.type === 'range-slider';
@@ -56,9 +60,43 @@ export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder,
     const handleToggleSyntaxHelp = useCallback(()=>{
         setShowSyntaxHelp((prev)=>!prev);
     }, []);
+    const handleDismissSuggestions = useCallback(()=>{
+        suggestionsSuppressedRef.current = true;
+        setSuggestionsOpen(false);
+    }, []);
+    const handleSuggestionsOpenChange = useCallback((open)=>{
+        if (open && suggestionsSuppressedRef.current) return;
+        setSuggestionsOpen(open);
+    }, []);
+    const handleEditorMouseDownCapture = useCallback(()=>{
+        suggestionsSuppressedRef.current = false;
+    }, []);
+    useEffect(()=>{
+        if (!suggestionsOpen) return;
+        const handleMouseDown = (event)=>{
+            if (isSelectingRef.current) return;
+            const target = event.target;
+            if (target && containerRef.current?.contains(target)) return;
+            if (target?.closest?.('[data-shipql-suggestions]')) return;
+            handleDismissSuggestions();
+            const activeElement = document.activeElement;
+            if (activeElement && containerRef.current?.contains(activeElement)) {
+                activeElement.blur();
+            }
+        };
+        document.addEventListener('mousedown', handleMouseDown, true);
+        return ()=>{
+            document.removeEventListener('mousedown', handleMouseDown, true);
+        };
+    }, [
+        suggestionsOpen,
+        handleDismissSuggestions
+    ]);
     return /*#__PURE__*/ _jsxs("div", {
+        ref: containerRef,
         "data-shipql-editor": true,
         className: cn('relative', className),
+        onMouseDownCapture: handleEditorMouseDownCapture,
         children: [
             mode === 'editor' ? /*#__PURE__*/ _jsxs(Popover, {
                 open: hasSuggestions && suggestionsOpen,
@@ -108,10 +146,12 @@ export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder,
                                 }),
                                 /*#__PURE__*/ _jsx(ShipQLPlugin, {
                                     onLeafFocus: handleLeafFocus,
-                                    formatLeafDisplay: formatLeafDisplay
+                                    formatLeafDisplay: formatLeafDisplay,
+                                    allowFreeText: allowFreeText
                                 }),
                                 /*#__PURE__*/ _jsx(OnBlurPlugin, {
-                                    onChange: onChange
+                                    onChange: onChange,
+                                    allowFreeText: allowFreeText
                                 }),
                                 /*#__PURE__*/ _jsx(OnTextChangePlugin, {
                                     onTextChange: onTextChange
@@ -125,7 +165,7 @@ export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder,
                                     valueSuggestions: valueSuggestions ?? [],
                                     isLoadingValueSuggestions: isLoadingValueSuggestions ?? false,
                                     open: suggestionsOpen,
-                                    setOpen: setSuggestionsOpen,
+                                    setOpen: handleSuggestionsOpenChange,
                                     selectedIndex: selectedIndex,
                                     setSelectedIndex: setSelectedIndex,
                                     items: items,
@@ -144,6 +184,7 @@ export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder,
                         selectedIndex: selectedIndex,
                         isSelectingRef: isSelectingRef,
                         onSelect: handleSelect,
+                        onClose: handleDismissSuggestions,
                         isLoading: isLoadingValueSuggestions,
                         isNegated: isNegated,
                         onToggleNegate: handleToggleNegate,
@@ -163,10 +204,11 @@ export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder,
                     className: "shrink-0 text-foreground-neutral-muted"
                 }),
                 className: cn(INPUT_CLASSES, disabled && 'pointer-events-none opacity-50'),
-                "aria-invalid": isError,
+                "aria-invalid": isError || isTextModeBlurError,
                 value: text,
                 onChange: (e)=>{
                     const newText = e.target.value;
+                    setIsTextModeBlurError(false);
                     onTextChange(newText);
                     const facetNames = facets ? normalizeFacets(facets) : [];
                     const facetCtx = detectFacetContext(newText, facetNames);
@@ -178,8 +220,11 @@ export default function ShipQLEditorInner({ onChange, onLeafFocus, placeholder,
                 },
                 onBlur: (e)=>{
                     const ast = tryParse(e.target.value);
-                    if (ast) onChange?.(ast);
+                    const hasDeferredFreeTextError = Boolean(ast && !allowFreeText && hasTextNodes(ast));
+                    setIsTextModeBlurError(hasDeferredFreeTextError);
+                    if (ast && !hasDeferredFreeTextError) onChange?.(ast);
                 },
+                onFocus: ()=>setIsTextModeBlurError(false),
                 placeholder: placeholder,
                 disabled: disabled
             }),

package/dist/components/shipql-editor/shipql-editor.d.ts

@@ -1,7 +1,7 @@
 import type { AstNode } from '@shipfox/shipql-parser';
-import type { LeafAstNode } from './lexical/shipql-leaf-node';
-import type { FacetDef, FormatLeafDisplay } from './suggestions/types';
-export type { FacetDef, FormatLeafDisplay, RangeFacetConfig } from './suggestions/types';
+import type { LeafAstNode } from './lexical/shipql-leaf-node.js';
+import type { FacetDef, FormatLeafDisplay } from './suggestions/types.js';
+export type { FacetDef, FacetMetadata, FormatLeafDisplay, RangeFacetConfig, } from './suggestions/types.js';
 export type LeafChangePayload = {
     partialValue: string;
     ast: AstNode | null;
@@ -20,6 +20,7 @@ export interface ShipQLEditorProps {
     isLoadingValueSuggestions?: boolean;
     onLeafChange?: (payload: LeafChangePayload) => void;
     formatLeafDisplay?: FormatLeafDisplay;
+    allowFreeText?: boolean;
 }
 export interface ShipQLEditorInnerProps extends ShipQLEditorProps {
     mode: 'editor' | 'text';

package/dist/components/shipql-editor/suggestions/generate-suggestions.d.ts

@@ -1,9 +1,15 @@
 import { type AstNode } from '@shipfox/shipql-parser';
-import type { LeafAstNode } from '../lexical/shipql-leaf-node';
-import type { FacetDef, RangeFacetConfig, SuggestionItem } from './types';
+import type { LeafAstNode } from '../lexical/shipql-leaf-node.js';
+import type { FacetDef, FacetGroupInfo, RangeFacetConfig, SuggestionItem } from './types.js';
 export declare function tryParse(text: string): AstNode | null;
 export declare function normalizeFacets(facets: FacetDef[]): string[];
-export declare function getFacetConfig(facets: FacetDef[], name: string): RangeFacetConfig | undefined;
+export declare function getFacetConfig(facets: FacetDef[], id: string): RangeFacetConfig | undefined;
+/** Returns the human-readable display label, falling back to the raw id. */
+export declare function getFacetLabel(facets: FacetDef[], id: string): string;
+/** Returns the description for a facet, if any. */
+export declare function getFacetDescription(facets: FacetDef[], id: string): string | undefined;
+/** Returns grouping information for a facet, with defaults applied. */
+export declare function getFacetGroupInfo(facets: FacetDef[], id: string): FacetGroupInfo;
 export declare function extractFacetFromLeaf(leaf: LeafAstNode): string | undefined;
 /** Extracts the negation prefix used in a `not` node's source (either 'NOT ' or '-'). */
 export declare function negationPrefixFromSource(source: string): string;