Merge dff3da47ff into 44a7813730

.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

@@ -72,7 +72,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]}
@@ -94,7 +95,10 @@ 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; before that, `getContext` returns the value set by the closest ancestor, if any.
  * Must be called during component initialisation.
  *
  * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
@@ -111,8 +115,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.
  *
@@ -144,8 +148,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}
@@ -156,9 +160,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,17 @@ 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; before that, `getContext` returns the value set by the closest ancestor, if any.
 	 * Must be called during component initialisation.
 	 *
 	 * [`createContext`](https://svelte.dev/docs/svelte/svelte#createContext) is a type-safe alternative.
@@ -509,8 +513,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 +523,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;