docs(graphql): stabilize query context references (#608)

* docs(graphql): stabilize query context references

* docs(graphql): clarify hook scope in query context example

* docs(graphql): explain why query context is hoisted and mutation context is not

Fix the dangling colon before the example, state that useQuery lists context as a hook dependency while the mutation second argument is per-call, and restore the query/mutation side comments.

Author: toiroakr

.changeset/stable-query-context-example.md

@@ -0,0 +1,6 @@
+---
+"@tailor-platform/app-shell": patch
+---
+
+Keep the GraphQL documentation and skill example's query context stable between renders.
+This avoids urql query re-execution loops when the example is used in a component.

docs-manifest.json

@@ -795,9 +795,9 @@
       "symbols": [],
       "hashes": {
         "typeSurface": null,
-        "outline": "c75d2a9a871756e6",
+        "outline": "37eafa8a70959a4d",
         "snapshot": null,
-        "outputMd": "ba5107604e4f42e8",
+        "outputMd": "a59a10293fba053b",
         "examples": null
       }
     },
@@ -1673,7 +1673,7 @@
     "packages/core/skills/app-shell-patterns/references/concepts/authentication.md": "71f5f42c0fa0698e",
     "packages/core/skills/app-shell-patterns/references/concepts/custom-components.md": "18b8fc747d52455a",
     "packages/core/skills/app-shell-patterns/references/concepts/file-based-routing.md": "e189f95dbe4b0286",
-    "packages/core/skills/app-shell-patterns/references/concepts/graphql.md": "ba5107604e4f42e8",
+    "packages/core/skills/app-shell-patterns/references/concepts/graphql.md": "a59a10293fba053b",
     "packages/core/skills/app-shell-patterns/references/concepts/modules-and-resources.md": "bf15b5460f22d165",
     "packages/core/skills/app-shell-patterns/references/concepts/routing-navigation.md": "8034c7f885994b29",
     "packages/core/skills/app-shell-patterns/references/concepts/sidebar-navigation.md": "e342ef02dc2b9b86",

docs-src/concepts/graphql.docs.outline.md

@@ -153,22 +153,28 @@ function CreateOrderButton() {
 
 ### `additionalTypenames`
 
-When a mutation creates/updates/deletes an entity that another query already has cached, urql won't know to refetch unless you pass `additionalTypenames`. Use it on **both** the query and the mutation when they share a typename:
+When a mutation creates/updates/deletes an entity that another query already has cached, urql won't know to refetch unless you pass `additionalTypenames`. Use it on **both** the query and the mutation when they share a typename.
+
+Define the query's static `context` at module scope, outside the component, so its reference stays stable between renders. `useQuery` lists `context` as a hook dependency, so a fresh object on each render re-creates the query subscription and can cause query re-execution loops. The mutation's second argument is passed per call and is not a hook dependency, so it can stay inline.
 
 ```tsx
-// Query side — declares it cares about the Order typename
-const [{ data }] = useQuery({
-  query: OrdersQuery,
-  variables: { first: 25 },
-  context: { additionalTypenames: ["Order"] },
-});
-
-// Mutation side — declares it produces Order writes
-const [, createOrder] = useMutation(CreateOrderMutation);
-await createOrder(
-  { input },
-  { additionalTypenames: ["Order"] }, // triggers refetch of any query subscribed to 'Order'
-);
+const ordersQueryContext = { additionalTypenames: ["Order"] };
+
+function useOrders() {
+  // Query side — declares it cares about the Order typename
+  const [{ data }] = useQuery({
+    query: OrdersQuery,
+    variables: { first: 25 },
+    context: ordersQueryContext,
+  });
+
+  // Mutation side — declares it produces Order writes
+  const [, executeCreateOrder] = useMutation(CreateOrderMutation);
+  const createOrder = (input: CreateOrderInput) =>
+    executeCreateOrder({ input }, { additionalTypenames: ["Order"] });
+
+  return { data, createOrder };
+}
 ```
 
 Skip `additionalTypenames` only when the mutation's return type already includes the affected entity _and_ every cached query for it touched the same `id` — urql will then refresh by id. When in doubt, add it.