v6: Query builder inline fragment extraction and editing (#4412)

## Summary

Reworks how the query builder handles fragments end to end.

**Extraction is now an inline row action.** Fragment extraction used to
be a single "Create fragment from selection" button pinned to the bottom
of the panel, acting on wherever the editor's text cursor happened to
sit. It now lives on the field rows: expand a composite field, tick the
children you want, and an "Extract to fragment" action appears on that
row. Triggering it lifts the selection into a named fragment and
replaces it with a spread (`user { ...UserFields }`). The generated name
(`UserFields`, de-duped when taken) stays editable in place from the
Fragments list.

**Extracted rows stay editable.** An extracted field no longer collapses
into a locked `...FragmentName` badge. It stays a normal, expandable
composite: the spread renders as a `...FragmentName` reference row among
the field's children, and ticking more fields adds them to the **base
query** alongside the spread. A field's only tie to its fragment is the
real spread in the document — it doesn't "remember" being extracted.

**Fragments are editable in place.** Because a fragment's contents are
shared across every field that spreads it, editing them needs its own
surface. The active editing target now **follows the editor cursor**:
move the cursor into a `fragment … { … }` block and the builder switches
to editing that fragment's tree, rooted at its type condition. You can
also jump in by clicking a `...FragmentName` reference row or a name in
the Fragments list; "Back to query" returns to the operation. Fragments
are flat peers — no nesting or breadcrumbs.

**The fragment reuse suggestion buttons are gone.** The short-lived "Use
...FragmentName" reuse action (and its dead helpers) is removed — it
crowded the row, and multiple matching fragments on one field overflowed
the small row.

The row actions are plain keyboard-focusable buttons. A dedicated
shortcut and keycap hint are left for the app-wide accessibility pass.

### Implementation notes

The document mutators and readers were generalized from an
operation-only `operationName` to a `DefinitionTarget` (`operation |
fragment`), so the same field tree and handlers drive operation and
fragment editing alike. Emptying a fragment is a no-op (a fragment can't
be emptied without orphaning its spreads); promote-arg-to-variable stays
operation-only.

## Test plan

- [x] Open the query builder against a schema. Expand a composite field
(e.g. `person`), tick a scalar child (e.g. `name`), and confirm an
"Extract to fragment" action appears on that row.
- [x] Trigger it. Confirm the query reads `person { ...PersonFields }`
with a `fragment PersonFields on Person { name }` block, and the
`person` row now shows a `...PersonFields` reference among its children.
- [x] With the field still expanded, tick another child (e.g. `age`).
Confirm it lands in the **base query** — `person { ...PersonFields age
}` — and the fragment is unchanged.
- [x] Click the `...PersonFields` reference row. Confirm a focused
fragment editor opens (header `PersonFields on Person`, "Back to query"
control), rooted at `Person`.
- [x] Tick a field in the fragment editor. Confirm it edits the fragment
(`fragment PersonFields on Person { name age }`) and the operation still
just spreads it.
- [x] Move the editor cursor into the `fragment PersonFields …` block.
Confirm the builder switches to editing that fragment. Move it back into
the operation; confirm it switches back.
- [x] Click a fragment's name in the Fragments list. Confirm it focuses
that fragment and is highlighted as active.
- [x] In the Fragments list, rename `PersonFields`. Confirm the
definition and every `...PersonFields` reference update together.
- [x] Keyboard-only: Tab to the extract action / reference row /
fragment name, confirm each takes focus and activates with Enter/Space.
- [x] Unit and `query-builder.cy.ts` suites pass; Storybook a11y check
clean.

Refs: #4219

Author: trevor-scheer

.changeset/query-builder.md

@@ -3,6 +3,6 @@
 'graphiql': minor
 ---
 
-Add `@graphiql/plugin-query-builder`, a first-party visual query builder. It renders the schema's root types as a collapsible tree; checking a field adds it to the current operation and unchecking removes it, with the document parsed, mutated, and reprinted through the `graphql` package's AST utilities. Fields expose argument inputs (scalars, enums, lists, and input objects, including lists of input objects), scalar arguments can be promoted to variables, named fragments can be created from a selection, and union/interface fields offer inline-fragment type-condition selectors.
+Add `@graphiql/plugin-query-builder`, a first-party visual query builder. It renders the schema's root types as a collapsible tree; checking a field adds it to the current operation and unchecking removes it, with the document parsed, mutated, and reprinted through the `graphql` package's AST utilities. Fields expose argument inputs (scalars, enums, lists, and input objects, including lists of input objects), scalar arguments can be promoted to variables, named fragments can be extracted from a field's selection and edited in place, and union/interface fields offer inline-fragment type-condition selectors.
 
 The query builder is default-installed in the `graphiql` meta-package, so it is available with no extra setup.

packages/graphiql-plugin-query-builder/src/components/__tests__/arg-input-reactive.spec.tsx

@@ -124,12 +124,14 @@ const ReactiveHarness: FC<HarnessProps> = ({
     }
   })();
 
-  const argValues = getFieldArgValues(doc, path);
+  const argValues = getFieldArgValues(doc, path, { kind: 'operation' });
   const value: ArgValue = argValues[argName] ?? [];
 
   const handleChange = (next: ArgValue) => {
     const valueNode = argValueToValueNode(arg.type, next);
-    const nextDoc = setFieldArgument(doc, path, argName, valueNode);
+    const nextDoc = setFieldArgument(doc, path, argName, valueNode, {
+      kind: 'operation',
+    });
     setQuery(print(nextDoc));
   };
 

packages/graphiql-plugin-query-builder/src/components/__tests__/field-row.spec.tsx

@@ -271,6 +271,63 @@ describe('FieldRow', () => {
   });
 });
 
+describe('FieldRow — extract to fragment', () => {
+  it('renders the extract action when onExtractFragment is supplied', () => {
+    render(
+      <FieldRow
+        field={friendsField}
+        path={[]}
+        selected={false}
+        hasChildren
+        expanded
+        onExtractFragment={() => {}}
+        onToggle={() => {}}
+        onExpand={() => {}}
+      />,
+    );
+    expect(
+      screen.getByRole('button', { name: /extract friends to a fragment/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('does not render the extract action when onExtractFragment is absent', () => {
+    render(
+      <FieldRow
+        field={friendsField}
+        path={[]}
+        selected={false}
+        hasChildren
+        expanded
+        onToggle={() => {}}
+        onExpand={() => {}}
+      />,
+    );
+    expect(
+      screen.queryByRole('button', { name: /extract .* to a fragment/i }),
+    ).not.toBeInTheDocument();
+  });
+
+  it('fires onExtractFragment when the action is clicked', async () => {
+    const onExtractFragment = vi.fn();
+    render(
+      <FieldRow
+        field={friendsField}
+        path={[]}
+        selected={false}
+        hasChildren
+        expanded
+        onExtractFragment={onExtractFragment}
+        onToggle={() => {}}
+        onExpand={() => {}}
+      />,
+    );
+    await userEvent.click(
+      screen.getByRole('button', { name: /extract friends to a fragment/i }),
+    );
+    expect(onExtractFragment).toHaveBeenCalledOnce();
+  });
+});
+
 describe('FieldRow — deprecated fields', () => {
   it('marks a deprecated field and surfaces the reason', async () => {
     render(

packages/graphiql-plugin-query-builder/src/components/__tests__/field-tree-cursor-reveal.spec.tsx

@@ -45,6 +45,7 @@ function renderTree(cursorPath?: PathSegment[]) {
       doc={doc('{ __typename }')}
       schema={schema}
       cursorPath={cursorPath}
+      target={{ kind: 'operation' }}
       onToggle={() => {}}
       onSetArg={() => {}}
     />,
@@ -78,6 +79,7 @@ describe('FieldTree — cursor reveal', () => {
         doc={doc('{ __typename }')}
         schema={schema}
         cursorPath={[fieldSegment('parent'), fieldSegment('child')]}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,

packages/graphiql-plugin-query-builder/src/components/__tests__/field-tree-union-interface.spec.tsx

@@ -132,6 +132,7 @@ describe('FieldTree — union field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithUnion}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -146,6 +147,7 @@ describe('FieldTree — union field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithUnion}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -163,6 +165,7 @@ describe('FieldTree — union field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithUnion}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -186,6 +189,7 @@ describe('FieldTree — union field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithUnion}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -212,6 +216,7 @@ describe('FieldTree — union field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithUnion}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
         onAddInlineFragment={onAdd}
@@ -234,6 +239,7 @@ describe('FieldTree — union field', () => {
         path={[]}
         doc={doc('{ search { ... on Human { name } } }')}
         schema={SchemaWithUnion}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
         onRemoveInlineFragment={onRemove}
@@ -257,6 +263,7 @@ describe('FieldTree — union field', () => {
         path={[]}
         doc={doc('{ search { ... on Droid { primaryFunction } } }')}
         schema={SchemaWithUnion}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -278,6 +285,7 @@ describe('FieldTree — interface field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithInterface}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -303,6 +311,7 @@ describe('FieldTree — interface field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithInterface}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -325,6 +334,7 @@ describe('FieldTree — interface field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithInterface}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -348,6 +358,7 @@ describe('FieldTree — interface field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithInterface}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -364,6 +375,7 @@ describe('FieldTree — interface field', () => {
         path={[]}
         doc={doc('{ character { ... on HumanCharacter { name } } }')}
         schema={SchemaWithInterface}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -383,6 +395,7 @@ describe('FieldTree — interface field', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithInterface}
+        target={{ kind: 'operation' }}
         onToggle={onToggle}
         onSetArg={() => {}}
       />,
@@ -408,6 +421,7 @@ describe('FieldTree — interface implementing interface', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithNode}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,
@@ -434,6 +448,7 @@ describe('FieldTree — interface implementing interface', () => {
         path={[]}
         doc={doc('{ __typename }')}
         schema={SchemaWithNode}
+        target={{ kind: 'operation' }}
         onToggle={() => {}}
         onSetArg={() => {}}
       />,

packages/graphiql-plugin-query-builder/src/components/__tests__/fragment-section.spec.tsx

@@ -34,43 +34,102 @@ describe('FragmentSection', () => {
     expect(screen.getByText('DroidFields')).toBeInTheDocument();
   });
 
-  it('renders the "create fragment from selection" button when onCreateFragment is supplied', () => {
+  it('has an accessible section label', () => {
+    render(<FragmentSection doc={doc('{ hero { name } }')} />);
+    expect(
+      screen.getByRole('region', { name: /fragments/i }),
+    ).toBeInTheDocument();
+  });
+
+  it('no longer renders a "create fragment from selection" button', () => {
+    const d = doc(`
+      { hero { ...HeroFields } }
+      fragment HeroFields on Hero { name }
+    `);
+    render(<FragmentSection doc={d} onRenameFragment={() => {}} />);
+    expect(
+      screen.queryByRole('button', { name: /create fragment from selection/i }),
+    ).not.toBeInTheDocument();
+  });
+});
+
+describe('FragmentSection — inline rename', () => {
+  const withFragment = () =>
+    doc(`
+      { hero { ...HeroFields } }
+      fragment HeroFields on Hero { name }
+    `);
+
+  it('shows a rename affordance per fragment when onRenameFragment is supplied', () => {
     render(
-      <FragmentSection
-        doc={doc('{ hero { name } }')}
-        onCreateFragment={() => {}}
-      />,
+      <FragmentSection doc={withFragment()} onRenameFragment={() => {}} />,
     );
     expect(
-      screen.getByRole('button', { name: /create fragment from selection/i }),
+      screen.getByRole('button', { name: /rename fragment HeroFields/i }),
     ).toBeInTheDocument();
   });
 
-  it('does not render the create button when onCreateFragment is not supplied', () => {
-    render(<FragmentSection doc={doc('{ hero { name } }')} />);
+  it('does not show a rename affordance without onRenameFragment', () => {
+    render(<FragmentSection doc={withFragment()} />);
     expect(
-      screen.queryByRole('button', { name: /create fragment from selection/i }),
+      screen.queryByRole('button', { name: /rename fragment/i }),
     ).not.toBeInTheDocument();
   });
 
-  it('calls onCreateFragment when the button is clicked', async () => {
-    const onCreateFragment = vi.fn();
+  it('commits a new name on Enter', async () => {
+    const onRenameFragment = vi.fn();
     render(
       <FragmentSection
-        doc={doc('{ hero { name } }')}
-        onCreateFragment={onCreateFragment}
+        doc={withFragment()}
+        onRenameFragment={onRenameFragment}
       />,
     );
     await userEvent.click(
-      screen.getByRole('button', { name: /create fragment from selection/i }),
+      screen.getByRole('button', { name: /rename fragment HeroFields/i }),
     );
-    expect(onCreateFragment).toHaveBeenCalledOnce();
+    const input = screen.getByRole('textbox', {
+      name: /rename fragment HeroFields/i,
+    });
+    await userEvent.clear(input);
+    await userEvent.type(input, 'HeroBasics{Enter}');
+    expect(onRenameFragment).toHaveBeenCalledWith('HeroFields', 'HeroBasics');
   });
 
-  it('has an accessible section label', () => {
-    render(<FragmentSection doc={doc('{ hero { name } }')} />);
-    expect(
-      screen.getByRole('region', { name: /fragments/i }),
-    ).toBeInTheDocument();
+  it('cancels on Escape without renaming', async () => {
+    const onRenameFragment = vi.fn();
+    render(
+      <FragmentSection
+        doc={withFragment()}
+        onRenameFragment={onRenameFragment}
+      />,
+    );
+    await userEvent.click(
+      screen.getByRole('button', { name: /rename fragment HeroFields/i }),
+    );
+    const input = screen.getByRole('textbox', {
+      name: /rename fragment HeroFields/i,
+    });
+    await userEvent.clear(input);
+    await userEvent.type(input, 'Nope{Escape}');
+    expect(onRenameFragment).not.toHaveBeenCalled();
+    expect(screen.getByText('HeroFields')).toBeInTheDocument();
+  });
+
+  it('does not fire a rename when the name is unchanged', async () => {
+    const onRenameFragment = vi.fn();
+    render(
+      <FragmentSection
+        doc={withFragment()}
+        onRenameFragment={onRenameFragment}
+      />,
+    );
+    await userEvent.click(
+      screen.getByRole('button', { name: /rename fragment HeroFields/i }),
+    );
+    const input = screen.getByRole('textbox', {
+      name: /rename fragment HeroFields/i,
+    });
+    await userEvent.type(input, '{Enter}');
+    expect(onRenameFragment).not.toHaveBeenCalled();
   });
 });