diff --git a/.changeset/context-docs-wording.md b/.changeset/context-docs-wording.md new file mode 100644 index 0000000000..6ec9d47ed9 --- /dev/null +++ b/.changeset/context-docs-wording.md @@ -0,0 +1,5 @@ +--- +'svelte': patch +--- + +docs: clarify that context lookup includes the current component and all ancestors diff --git a/documentation/docs/98-reference/.generated/shared-errors.md b/documentation/docs/98-reference/.generated/shared-errors.md index 739bd58b35..d7596fc068 100644 --- a/documentation/docs/98-reference/.generated/shared-errors.md +++ b/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 diff --git a/packages/svelte/messages/shared-errors/errors.md b/packages/svelte/messages/shared-errors/errors.md index 3ff474768e..43dca57ac8 100644 --- a/packages/svelte/messages/shared-errors/errors.md +++ b/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 diff --git a/packages/svelte/src/internal/client/context.js b/packages/svelte/src/internal/client/context.js index 0baef5c63e..337a19f8f3 100644 --- a/packages/svelte/src/internal/client/context.js +++ b/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} [T=Map] * @returns {T} diff --git a/packages/svelte/src/internal/shared/errors.js b/packages/svelte/src/internal/shared/errors.js index a4ad8cecff..9e41788dc1 100644 --- a/packages/svelte/src/internal/shared/errors.js +++ b/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'; diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts index d758022ae4..f5e491b9e3 100644 --- a/packages/svelte/types/index.d.ts +++ b/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, (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(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(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 = Map>(): T;