Merge branch 'main' into feat/how-it-works

Author: kodiakhq[bot]

src/middleware/legacy-routes-redirect.ts

@@ -59,7 +59,7 @@ const LEGACY_ROUTES = {
 	"/references/api-reference/secondary-primitives/createSelector": "/reference/secondary-primitives/create-selector",
 	"/references/api-reference/special-jsx-attributes/attr_": "/reference/jsx-attributes/attr",
 	"/references/api-reference/special-jsx-attributes/classList": "/reference/jsx-attributes/classlist",
-	"/references/api-reference/special-jsx-attributes/innerHTML-or-textContent": "/reference/jsx-attributes/innerhtml-or-textcontent",
+	"/references/api-reference/special-jsx-attributes/innerHTML-or-textContent": "/reference/jsx-attributes/innerhtml",
 	"/references/api-reference/special-jsx-attributes/on_": "/reference/jsx-attributes/on_",
 	"/references/api-reference/special-jsx-attributes/on_-and-oncapture_": "/reference/jsx-attributes/on",
 

src/routes/concepts/control-flow/error-boundary.mdx

@@ -3,26 +3,39 @@ title: "Error boundary"
 order: 5
 ---
 
-`<ErrorBoundary>` is a component that can be used to catch errors thrown by child components.
-When encountering an error, this component will render a fallback UI instead of the problematic child component(s).
+By default, if part of an application throws an error during rendering, the entire application can crash, resulting in Solid removing its UI from the screen.
+Error boundaries provide a way to catch these errors and prevent the entire app from crashing.
 
-```jsx
-import { ErrorBoundary } from "solid-js";
-
-<ErrorBoundary fallback={(err) => <div>Error: {err.message}</div>}>
-	<ProblematicComponent />
-</ErrorBoundary>
-```
+The [`<ErrorBoundary>`](/reference/components/error-boundary) component is used to create an error boundary.
+It catches any error that occurs during the rendering or updating of its children.
+However, an important note is that errors occurring outside the rendering process, such as in event handlers or after a `setTimeout`, are _not_ caught by error boundaries.
 
-`<ErrorBoundary>` accepts a `fallback` prop that can be used to render a custom error message, or to provide a friendly notification to the user.
-This prop accepts a function that receives the caught error as an argument, providing a flexible way to handle different error scenarios.
+The `fallback` prop can be used to display a user-friendly error message or notification when an error occurs.
+If a function is passed to `fallback`, it will receive the error object as well as a `reset` function.
+The `reset` function forces the `<ErrorBoundary>` to re-render its children and reset the error state, providing users with a way to recover from the error.
 
-<EraserLink
-	href="https://app.eraser.io/workspace/maDvFw5OryuPJOwSLyK9?elements=aSw5yYrSY22mI_YqoZlpGQ"
-	preview="https://app.eraser.io/workspace/maDvFw5OryuPJOwSLyK9/preview?elements=aSw5yYrSY22mI_YqoZlpGQ&type=embed"
-/>
+```tsx
+import { ErrorBoundary } from "solid-js";
+import { Header, ErrorProne } from "./components";
 
-By wrapping parts of your application in `<ErrorBoundary>`, you can prevent the entire application from crashing when an error occurs due to a single component.
+function App() {
+	return (
+		<div>
+			<Header />
+			<ErrorBoundary
+				fallback={(error, reset) => (
+					<div>
+						<p>Something went wrong: {error.message}</p>
+						<button onClick={reset}>Try Again</button>
+					</div>
+				)}
+			>
+				<ErrorProne />
+			</ErrorBoundary>
+		</div>
+	);
+}
+```
 
-When an error is encountered, the `<ErrorBoundary>` component will catch the error and render the fallback UI instead of the problematic component(s).
-This way, even when a component fails, the user has a controlled UI response instead of a broken interface.
+In this example, when the `ErrorProne` component throws an error, the `<ErrorBoundary>` catches it, preventing it from affecting the rest of the application.
+Instead, it displays the error message passed to the fallback prop.

src/routes/configuration/environment-variables.mdx

@@ -59,7 +59,7 @@ function MyComponent() {
 
 ## Private Environment Variables
 
-These variables should only be accessed in your backend code, so it's best not to use the `VITE_` prefix for them. Instead, use `process.env` to access them. Depending on the [Nitro preset](https://nitro.unjs.io/deploy) chosen, they'll be made available automatically or they will require an external dependency such as [dotenv](https://www.npmjs.com/package/dotenv).
+These variables should only be accessed in your backend code, so it's best not to use the `VITE_` prefix for them. Instead, use `process.env` to access them. Depending on the [Nitro preset](https://nitro.build/deploy) chosen, they'll be made available automatically or they will require an external dependency such as [dotenv](https://www.npmjs.com/package/dotenv).
 
 ```jsx
 DB_HOST="somedb://192.110.0"

src/routes/guides/fetching-data.mdx

@@ -74,6 +74,12 @@ The `Switch/Match` construct provides one way to manage these conditions.
 When the fetch succeeds and user data is retrieved, the `user()` condition becomes active, and its related block executes.
 However, if there's an error while fetching, the `user.error` block becomes `true`, leading to its corresponding `Match` block being shown.
 
+:::tip
+
+If you anticipate errors, you may want to wrap `createResource` in an [ErrorBoundary](/reference/components/error-boundary).
+  
+:::
+
 In addition to the `error` property, the `loading` property offers a way to display a loading state to the user during the fetch operation.
 
 

src/routes/reference/components/error-boundary.mdx

@@ -3,38 +3,52 @@ title: <ErrorBoundary>
 order: 5
 ---
 
-Catches uncaught errors and renders fallback content.
+The `<ErrorBoundary>` component catches errors that occur during the rendering or updating of its children and shows a fallback UI instead.
+This includes:
 
-```tsx
-import { ErrorBoundary } from "solid-js"
-import type { JSX } from "solid-js"
+- Errors that occur while rendering JSX.
+- Errors that occur within `createEffect`, `createMemo`, and other state management primitives.
+- Errors that occur within `createResource` and other asynchronous state management or data-fetching primitives.
 
-function ErrorBoundary(props: {
-	fallback: JSX.Element | ((err: any, reset: () => void) => JSX.Element)
-	children: JSX.Element
-}): () => JSX.Element
-```
+However, errors occurring outside the rendering process are **not** captured by error boundaries.
+For instance:
 
-Here's an example of how to use it:
+- Errors that occur inside event handlers.
+- Errors that occur after a `setTimeout`.
 
-```tsx
-<ErrorBoundary fallback={<div>Something went terribly wrong</div>}>
-	<MyComp />
-</ErrorBoundary>
-```
+## Props
 
-If you want to customize the error message, you can pass a function as the `fallback` prop. The function will be called with the error and a `reset` function. The `reset` function will reset the error boundary and re-render the children.
+### `fallback`
 
-```tsx
-<ErrorBoundary
-	fallback={(err, reset) => <div onClick={reset}>Error: {err.toString()}</div>}
->
-	<MyComp />
-</ErrorBoundary>
-```
+**Type**: `JSX.Element | ((err: any, reset: () => void) => JSX.Element)`
 
-## Props
+`fallback` provides content to display when an error occurs.
+If a function is passed, it receives two parameters:
+
+- `err`: The caught error object.
+- `reset`: A function that forces the `<ErrorBoundary>` to re-render its children and clear the error state.
+
+If there's an error within the `fallback` itself, however, it is not caught by the same `<ErrorBoundary>`.
+Instead, it will bubble up to any parent error boundaries.
 
-| Name       | Type                                                            | Description                                             |
-| :--------- | :-------------------------------------------------------------- | :------------------------------------------------------ |
-| `fallback` | `JSX.Element \| ((err: any, reset: () => void) => JSX.Element)` | The fallback content to render when an error is caught. |
+## Example
+
+```tsx
+import { ErrorBoundary } from "solid-js";
+import { ErrorProne } from "./components";
+
+function Example() {
+	return (
+		<ErrorBoundary
+			fallback={(error, reset) => (
+				<div>
+					<p>{error.message}</p>
+					<button onClick={reset}>Try Again</button>
+				</div>
+			)}
+		>
+			<ErrorProne />
+		</ErrorBoundary>
+	);
+}
+```

src/routes/reference/jsx-attributes/data.json

@@ -4,7 +4,8 @@
 		"attr.mdx",
 		"classlist.mdx",
 		"bool.mdx",
-		"innerhtml-or-textcontent.mdx",
+		"innerhtml.mdx",
+		"textcontent.mdx",
 		"on_.mdx",
 		"on.mdx",
 		"once.mdx",

src/routes/reference/jsx-attributes/innerhtml-or-textcontent.mdx

@@ -0,0 +1,12 @@
+---
+title: innerHTML
+---
+
+The `innerHTML` attribute is equivalent to the [`innerHTML` DOM property](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML).
+This attribute replaces all existing nodes of the element with new nodes generated by parsing the provided string as HTML.
+
+:::caution
+
+Using `innerHTML` with unsanitized user-supplied data can introduce security vulnerabilities.
+
+:::

src/routes/reference/jsx-attributes/innerhtml.mdx

@@ -0,0 +1,8 @@
+---
+title: textContent
+---
+
+The `textContent` attribute is equivalent to the [`textContent` DOM property](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
+This attribute replaces all existing child nodes of the element with a single text node containing the provided string.
+
+Using `textContent` can improve performance when the element's children are known to be exclusively text, as it bypasses the generic diffing process.

src/routes/reference/jsx-attributes/textcontent.mdx

@@ -9,14 +9,11 @@ function batch<T>(fn: () => T): T
 ```
 
 `batch` is a low-level API that batches updates together.
-More precisely, `batch(fn)` holds the execution of downstream computations
-during the `fn` block, executing them all together once the block `fn` returns.
-Thus, instead of a downstream computation executing after every dependency
-update, it will update just once at the end of the batch.
+More precisely, `batch(fn)` holds the execution of downstream computations during the `fn` block, executing them all together once the block `fn` returns.
+Thus, instead of a downstream computation executing after every dependency update, it will update just once at the end of the batch.
 
 Batching improves performance by avoiding unnecessary recalculation.
-Suppose you have a downstream memo `down` that depends on
-multiple upstream signals `up1`, `up2`, and `up3`:
+Suppose you have a downstream memo `down` that depends on multiple upstream signals `up1`, `up2`, and `up3`:
 
 ```ts
 import { createSignal, createMemo, createEffect } from "solid-js"
@@ -28,17 +25,15 @@ const down = createMemo(() => up1() + up2() + up3())
 createEffect(() => console.log(down())) // outputs 6
 ```
 
-If you directly update all of the upstream signals outside of batch mode,
-then `down` will recompute every time.
+If you directly update all of the upstream signals outside of batch mode, then `down` will recompute every time.
 
 ```ts
 setUp1(4) // recomputes down, outputs 9
 setUp2(5) // recomputes down, outputs 12
 setUp3(6) // recomputes down, outputs 15
 ```
 
-If instead you update the upstream signals within a `batch`, then `down`
-will update only once at the end:
+If instead you update the upstream signals within a `batch`, then `down` will update only once at the end:
 
 ```ts
 batch(() => {
@@ -48,33 +43,21 @@ batch(() => {
 }) // recomputes down, outputs 30
 ```
 
-The impact is even more dramatic if you have *m* downstream computations
-(memos, effects, etc.) that each depend on *n* upstream signals.
-Without batching, modifying all *n* upstream signals
-would cause *m n* updates to the downstream computations.
-With batching, modifying all *n* upstream signals
-would cause *m* updates to the downstream computations.
-Given that each update takes at least *n* time
-(just to read the upstream signals), this cost savings can be significant.
-Batching is also especially helpful when the downstream effects include
-DOM updates, which can be expensive.
+The impact is even more dramatic if you have *m* downstream computations (memos, effects, etc.) that each depends on *n* upstream signals.
+Without batching, modifying all *n* upstream signals would cause *m n* updates to the downstream computations.
+With batching, modifying all *n* upstream signals would cause *m* updates to the downstream computations.
+Given that each update takes at least *n* time (just to read the upstream signals), this cost savings can be significant.
+Batching is also especially helpful when the downstream effects include DOM updates, which can be expensive.
 
-Solid uses `batch` internally to automatically batch updates for you
-in a few cases:
+Solid uses `batch` internally to automatically batch updates for you in a few cases:
 
-* Within [`createEffect`](/reference/basic-reactivity/create-effect)
-  and [`onMount`](/reference/lifecycle/on-mount)
-  (unless they are outside a [root](/reference/reactive-utilities/create-root))
-* Within the [setter of a store](/reference/store-utilities/create-store#setter)
-  (which can update several properties at once)
-* Within array methods (e.g. `Array.prototype.splice`) of a
-  [mutable store](/reference/store-utilities/create-mutable)
-  (which can update several elements at once)
+* Within [`createEffect`](/reference/basic-reactivity/create-effect) and [`onMount`](/reference/lifecycle/on-mount) (unless they are outside a [root](/reference/reactive-utilities/create-root))
+* Within the [setter of a store](/reference/store-utilities/create-store#setter) (which can update several properties at once)
+* Within array methods (e.g. `Array.prototype.splice`) of a [mutable store](/reference/store-utilities/create-mutable) (which can update several elements at once)
 
 These save you from having to use `batch` yourself in many cases.
-For the most part, automatic batching should be transparent to you,
-because accessing a signal or memo will cause it to update if it is out of date
-(as of Solid 1.4).  For example:
+For the most part, automatic batching should be transparent to you, because accessing a signal or memo will cause it to update if it is out of date (as of Solid 1.4).
+For example:
 
 ```ts
 batch(() => {
@@ -88,9 +71,6 @@ batch(() => {
 }) // recomputes down, outputs 36
 ```
 
-You can think of `batch(fn)` as setting a global "batch mode" variable,
-calling the function `fn`, and then restoring the global variable to its
-previous value.
+You can think of `batch(fn)` as setting a global "batch mode" variable, calling the function `fn`, and then restoring the global variable to its previous value.
 This means that you can nest `batch` calls, and they will form one big batch.
-It also means that, if `fn` is asynchronous,
-only the updates before the first `await` will be batched.
+It also means that, if `fn` is asynchronous, only the updates before the first `await` will be batched.