docs: clarify that context lookup includes the current component and all ancestors (#18581)

Fixes #7916. Context lookup starts at the current component, not the
closest parent. `setContext` followed by `getContext` with the same key
in the same component returns the value.
---------

Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>

.changeset/context-docs-wording.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+docs: clarify that context lookup includes the current component and all ancestors

documentation/docs/98-reference/.generated/shared-errors.md

@@ -75,10 +75,10 @@ Certain lifecycle methods can only be used during component initialisation. To f
 ### missing_context
 
 ```
-Context was not set in a parent component
+Context was not set in the current component or any of its ancestors
 ```
 
-The [`createContext()`](svelte#createContext) utility returns a `[get, set]` pair of functions. `get` will throw an error if `set` was not used to set the context in a parent component.
+The [`createContext()`](svelte#createContext) utility returns a `[get, set]` pair of functions. `get` will throw an error if `set` was not used to set the context in the current component or any of its ancestors.
 
 ### snippet_without_render_tag
 

packages/svelte/messages/shared-errors/errors.md

@@ -62,9 +62,9 @@ Certain lifecycle methods can only be used during component initialisation. To f
 
 ## missing_context
 
-> Context was not set in a parent component
+> Context was not set in the current component or any of its ancestors
 
-The [`createContext()`](svelte#createContext) utility returns a `[get, set]` pair of functions. `get` will throw an error if `set` was not used to set the context in a parent component.
+The [`createContext()`](svelte#createContext) utility returns a `[get, set]` pair of functions. `get` will throw an error if `set` was not used to set the context in the current component or any of its ancestors.
 
 ## snippet_without_render_tag
 

packages/svelte/src/internal/client/context.js

@@ -73,7 +73,8 @@ export function set_dev_current_component_function(fn) {
 /**
  * Returns a `[get, set]` pair of functions for working with context in a type-safe way.
  *
- * `get` will throw an error if no parent component called `set`.
+ * `get` will throw an error if `set` has not yet been called in the current component or any of
+ * its ancestors.
  *
  * @template T
  * @returns {[() => T, (context: T) => T]}
@@ -86,7 +87,9 @@ export function createContext() {
 }
 
 /**
- * Retrieves the context that belongs to the closest parent component with the specified `key`.
+ * Retrieves the context set with the specified `key` in the current component or any of its
+ * ancestors. If multiple components set the same key, the value from the closest one is returned.
+ * A `setContext` call in the current component is only visible to `getContext` calls that run after it.
  * Must be called during component initialisation.
  *
  * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
@@ -103,8 +106,8 @@ export function getContext(key) {
 
 /**
  * Associates an arbitrary `context` object with the current component and the specified `key`
- * and returns that object. The context is then available to children of the component
- * (including slotted content) with `getContext`.
+ * and returns that object. The context is then available to the component itself and all of its
+ * descendants (including slotted content) with `getContext`.
  *
  * Like lifecycle functions, this must be called during component initialisation.
  *
@@ -136,8 +139,8 @@ export function setContext(key, context) {
 }
 
 /**
- * Checks whether a given `key` has been set in the context of a parent component.
- * Must be called during component initialisation.
+ * Checks whether a given `key` has been set in the context of the current component or any of
+ * its ancestors. Must be called during component initialisation.
  *
  * @param {any} key
  * @returns {boolean}
@@ -148,9 +151,9 @@ export function hasContext(key) {
 }
 
 /**
- * Retrieves the whole context map that belongs to the closest parent component.
- * Must be called during component initialisation. Useful, for example, if you
- * programmatically create a component and want to pass the existing context to it.
+ * Retrieves the whole context map that belongs to the current component, including entries
+ * inherited from its ancestors. Must be called during component initialisation. Useful, for
+ * example, if you programmatically create a component and want to pass the existing context to it.
  *
  * @template {Map<any, any>} [T=Map<any, any>]
  * @returns {T}

packages/svelte/src/internal/shared/errors.js

@@ -86,12 +86,12 @@ export function lifecycle_outside_component(name) {
 }
 
 /**
- * Context was not set in a parent component
+ * Context was not set in the current component or any of its ancestors
  * @returns {never}
  */
 export function missing_context() {
 	if (DEV) {
-		const error = new Error(`missing_context\nContext was not set in a parent component\nhttps://svelte.dev/e/missing_context`);
+		const error = new Error(`missing_context\nContext was not set in the current component or any of its ancestors\nhttps://svelte.dev/e/missing_context`);
 
 		error.name = 'Svelte error';
 

packages/svelte/types/index.d.ts

@@ -494,13 +494,16 @@ declare module 'svelte' {
 	/**
 	 * Returns a `[get, set]` pair of functions for working with context in a type-safe way.
 	 *
-	 * `get` will throw an error if no parent component called `set`.
+	 * `get` will throw an error if `set` has not yet been called in the current component or any of
+	 * its ancestors.
 	 *
 	 * @since 5.40.0
 	 */
 	export function createContext<T>(): [() => T, (context: T) => T];
 	/**
-	 * Retrieves the context that belongs to the closest parent component with the specified `key`.
+	 * Retrieves the context set with the specified `key` in the current component or any of its
+	 * ancestors. If multiple components set the same key, the value from the closest one is returned.
+	 * A `setContext` call in the current component is only visible to `getContext` calls that run after it.
 	 * Must be called during component initialisation.
 	 *
 	 * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
@@ -509,8 +512,8 @@ declare module 'svelte' {
 	export function getContext<T>(key: any): T;
 	/**
 	 * Associates an arbitrary `context` object with the current component and the specified `key`
-	 * and returns that object. The context is then available to children of the component
-	 * (including slotted content) with `getContext`.
+	 * and returns that object. The context is then available to the component itself and all of its
+	 * descendants (including slotted content) with `getContext`.
 	 *
 	 * Like lifecycle functions, this must be called during component initialisation.
 	 *
@@ -519,15 +522,15 @@ declare module 'svelte' {
 	 * */
 	export function setContext<T>(key: any, context: T): T;
 	/**
-	 * Checks whether a given `key` has been set in the context of a parent component.
-	 * Must be called during component initialisation.
+	 * Checks whether a given `key` has been set in the context of the current component or any of
+	 * its ancestors. Must be called during component initialisation.
 	 *
 	 * */
 	export function hasContext(key: any): boolean;
 	/**
-	 * Retrieves the whole context map that belongs to the closest parent component.
-	 * Must be called during component initialisation. Useful, for example, if you
-	 * programmatically create a component and want to pass the existing context to it.
+	 * Retrieves the whole context map that belongs to the current component, including entries
+	 * inherited from its ancestors. Must be called during component initialisation. Useful, for
+	 * example, if you programmatically create a component and want to pass the existing context to it.
 	 *
 	 * */
 	export function getAllContexts<T extends Map<any, any> = Map<any, any>>(): T;