solid-js 2.0.0-beta.8 → 2.0.0-beta.9

package/README.md

@@ -2,222 +2,78 @@
   <img src="https://assets.solidjs.com/banner?project=Library&type=core" alt="SolidJS" />
 </p>
 
-[![Build Status](https://img.shields.io/github/actions/workflow/status/solidjs/solid/main-ci.yml?branch=main&logo=github&style=for-the-badge)](https://github.com/solidjs/solid/actions/workflows/main-ci.yml)
-[![Coverage Status](https://img.shields.io/coveralls/github/solidjs/solid.svg?style=for-the-badge)](https://coveralls.io/github/solidjs/solid?branch=main)
-
 [![NPM Version](https://img.shields.io/npm/v/solid-js.svg?style=for-the-badge)](https://www.npmjs.com/package/solid-js)
 [![](https://img.shields.io/npm/dm/solid-js.svg?style=for-the-badge)](https://www.npmjs.com/package/solid-js)
 [![Discord](https://img.shields.io/discord/722131463138705510?style=for-the-badge)](https://discord.com/invite/solidjs)
-[![Subreddit subscribers](https://img.shields.io/reddit/subreddit-subscribers/solidjs?style=for-the-badge)](https://www.reddit.com/r/solidjs/)
-
-**[Website](https://www.solidjs.com/) • [API Docs](https://docs.solidjs.com/) • [Features Tutorial](https://www.solidjs.com/tutorial/introduction_basics) • [Playground](https://playground.solidjs.com/?version=1.3.13#NobwRAdghgtgpmAXGGUCWEwBowBcCeADgsrgM4Ae2YZA9gK4BOAxiWGjIbY7gAQi9GcCABM4jXgF9eAM0a0YvADo1aAGzQiAtACsyAegDucAEYqA3EogcuPfr2ZCouOAGU0Ac2hqps+YpU6DW09CysrGXoIZlw0WgheAGEGCBdGAAoASn4rXgd4sj5gZhTcLF4yOFxkqNwAXV4AXgcnF3cvKDV0gAZMywT8iELeDEc4eFSm3iymgD4KqprU9JLamYBqXgBGPvCBoVwmBPTcvN4AHhN6XFx43gJiRpUrm-iVXnjEjWYAa0aQUZCCa4SSzU5nfirZaZSTgi76F63CBgga7CCwiBWISicTpGaNebnJZpXj6WblES0Zj0YEAOg8VQAompxsJcAAhfAASREJzAUEIhBUmTRYEkdSAA) • [Discord](https://discord.com/invite/solidjs)**
-
-Solid is a declarative JavaScript library for creating user interfaces. Instead of using a Virtual DOM, it compiles its templates to real DOM nodes and updates them with fine-grained reactions. Declare your state and use it throughout your app, and when a piece of state changes, only the code that depends on it will rerun. Check out our [intro video](https://www.youtube.com/watch?v=cELFZQAMdhQ) or read on!
-
-## Key Features
-
-- Fine-grained updates to the real DOM
-- Declarative data: model your state as a system with reactive primitives
-- Render-once mental model: your components are regular JavaScript functions that run once to set up your view
-- Automatic dependency tracking: accessing your reactive state subscribes to it
-- [Small](https://dev.to/this-is-learning/javascript-framework-todomvc-size-comparison-504f) and [fast](https://krausest.github.io/js-framework-benchmark/current.html)
-- Simple: learn a few powerful concepts that can be reused, combined, and built on top of
-- Provides modern framework features like JSX, fragments, Context, Portals, Suspense, streaming SSR, progressive hydration, Error Boundaries and concurrent rendering.
-- Naturally debuggable: A `<div>` is a real div, so you can use your browser's devtools to inspect the rendering
-- [Web component friendly](https://github.com/solidjs/solid/tree/main/packages/solid-element#readme) and can author custom elements
-- Isomorphic: render your components on the client and the server
-- Universal: write [custom renderers](https://github.com/solidjs/solid/releases/tag/v1.2.0) to use Solid anywhere
-- A growing community and ecosystem with active core team support
-
-<details>
-
-<summary>Quick Start</summary>
-
-You can get started with a simple app by running the following in your terminal:
-
-```sh
-> npx degit solidjs/templates/js my-app
-> cd my-app
-> npm i # or yarn or pnpm
-> npm run dev # or yarn or pnpm
-```
-
-Or for TypeScript:
-
-```sh
-> npx degit solidjs/templates/ts my-app
-> cd my-app
-> npm i # or yarn or pnpm
-> npm run dev # or yarn or pnpm
-```
-
-This will create a minimal, client-rendered application powered by [Vite](https://vitejs.dev/).
-
-Or you can install the dependencies in your own setup. To use Solid with JSX (_recommended_), run:
-
-```sh
-> npm i -D babel-preset-solid
-> npm i solid-js
-```
-
-The easiest way to get set up is to add `babel-preset-solid` to your `.babelrc`, babel config for webpack, or rollup configuration:
-
-```js
-"presets": ["solid"]
-```
-
-For TypeScript to work, remember to set your `.tsconfig` to handle Solid's JSX:
-
-```js
-"compilerOptions": {
-  "jsx": "preserve",
-  "jsxImportSource": "solid-js",
-}
-```
-
-</details>
 
-## Why Solid?
+**[Website](https://www.solidjs.com/) • [API Docs](https://docs.solidjs.com/) • [Tutorial](https://www.solidjs.com/tutorial/introduction_basics) • [GitHub](https://github.com/solidjs/solid) • [Discord](https://discord.com/invite/solidjs)**
 
-### Performant
+> **You are looking at Solid 2.0 (experimental beta).**
+> Public surface differs from 1.x — split-phase `createEffect`, microtask batching, `Loading`/`Errored` boundaries, draft-first store setters, async-in-computations, removed `solid-js/web` and `solid-js/store` subpaths, and more.
+>
+> - **Migrating from 1.x?** Read [MIGRATION.md](https://github.com/solidjs/solid/blob/next/documentation/solid-2.0/MIGRATION.md) (full guide).
+> - **Need a quick API reference?** See [CHEATSHEET.md](./CHEATSHEET.md) (one page, every public export — ships with this package).
+> - **Looking for stable Solid 1.x?** Use the default [`main` branch](https://github.com/solidjs/solid).
 
-Meticulously engineered for performance and with half a decade of research behind it, Solid's performance is almost indistinguishable from optimized vanilla JavaScript (See Solid on the [JS Framework Benchmark](https://krausest.github.io/js-framework-benchmark/current.html)). Solid is [small](https://bundlephobia.com/package/solid-js@1.3.15) and completely tree-shakable, and [fast](https://levelup.gitconnected.com/how-we-wrote-the-fastest-javascript-ui-framework-again-db097ddd99b6) when rendering on the server, too. Whether you're writing a fully client-rendered SPA or a server-rendered app, your users see it faster than ever. ([Read more about Solid's performance](https://dev.to/ryansolid/thinking-granular-how-is-solidjs-so-performant-4g37) from the library's creator.)
+Solid is a declarative JavaScript library for building user interfaces. Instead of a Virtual DOM, it compiles templates to real DOM nodes and updates them with fine-grained reactivity. Declare your state and use it throughout your app — when a piece of state changes, only the code that depends on it re-runs.
 
-### Powerful
+## At a glance (Solid 2.0)
 
-Solid is fully-featured with everything you can expect from a modern framework. Performant state management is built-in with Context and Stores: you don't have to reach for a third party library to manage global state (if you don't want to). With Resources, you can use data loaded from the server like any other piece of state and build a responsive UI for it thanks to Suspense and concurrent rendering. And when you're ready to move to the server, Solid has full SSR and serverless support, with streaming and progressive hydration to get to interactive as quickly as possible. (Check out our full [interactive features walkthrough](https://www.solidjs.com/tutorial/introduction_basics).)
-
-### Pragmatic
-
-Do more with less: use simple, composable primitives without hidden rules and gotchas. In Solid, components are just functions - rendering is determined purely by how your state is used - so you're free to organize your code how you like and you don't have to learn a new rendering system. Solid encourages patterns like declarative code and read-write segregation that help keep your project maintainable, but isn't opinionated enough to get in your way.
-
-### Productive
-
-Solid is built on established tools like JSX and TypeScript and integrates with the Vite ecosystem. Solid's bare-metal, minimal abstractions give you direct access to the DOM, making it easy to use your favorite native JavaScript libraries like D3. And the Solid ecosystem is growing fast, with [custom primitives](https://github.com/solidjs-community/solid-primitives), [component libraries](https://github.com/hope-ui/hope-ui), and build-time utilities that let you [write Solid code in new ways](https://github.com/LXSMNSYC/solid-labels).
-
-<details>
-<summary>Show Me!</summary>
-
-```jsx
-import { render } from "solid-js/web";
+```tsx
 import { createSignal } from "solid-js";
+import { render } from "@solidjs/web";
 
-// A component is just a function that (optionally) accepts properties and returns a DOM node
-const Counter = props => {
-  // Create a piece of reactive state, giving us a accessor, count(), and a setter, setCount()
-  const [count, setCount] = createSignal(props.startingCount || 1);
-
-  // The increment function calls the setter
-  const increment = () => setCount(count() + 1);
+function Counter() {
+  const [count, setCount] = createSignal(0);
+  const doubled = () => count() * 2;
 
-  console.log(
-    "The body of the function runs once, like you'd expect from calling any other function, so you only ever see this console log once."
-  );
-
-  // JSX allows us to write HTML within our JavaScript function and include dynamic expressions using the { } syntax
-  // The only part of this that will ever rerender is the count() text.
   return (
-    <button type="button" onClick={increment}>
-      Increment {count()}
+    <button onClick={() => setCount(c => c + 1)}>
+      {doubled()}
     </button>
   );
-};
+}
 
-// The render function mounts a component onto your page
-render(() => <Counter startingCount={2} />, document.getElementById("app"));
+render(() => <Counter />, document.getElementById("app")!);
 ```
 
-See it in action in our interactive [Playground](https://playground.solidjs.com/?hash=-894962706&version=1.3.13)!
-
-Solid compiles our JSX down to efficient real DOM expressions updates, still using the same reactive primitives (`createSignal`) at runtime but making sure there's as little rerendering as possible. Here's what that looks like in this example:
-
-```js
-import { render, createComponent, delegateEvents, insert, template } from "solid-js/web";
-import { createSignal } from "solid-js";
-
-const _tmpl$ = /*#__PURE__*/ template(`<button type="button">Increment </button>`, 2);
+Try it in our [Playground](https://playground.solidjs.com/). _(The hosted Playground currently runs Solid 1.x — a 2.0 build is on the way.)_
 
-const Counter = props => {
-  const [count, setCount] = createSignal(props.startingCount || 1);
-  const increment = () => setCount(count() + 1);
+The component body runs **once**. The `{doubled()}` expression is the only thing that re-renders when `count` changes — Solid compiles JSX to real DOM nodes and tracks the `count()` read at that one DOM position.
 
-  console.log("The body of the function runs once . . .");
+## Install
 
-  return (() => {
-    //_el$ is a real DOM node!
-    const _el$ = _tmpl$.cloneNode(true);
-    _el$.firstChild;
-
-    _el$.$$click = increment;
-
-    //This inserts the count as a child of the button in a way that allows count to update without rerendering the whole button
-    insert(_el$, count, null);
-
-    return _el$;
-  })();
-};
-
-render(
-  () =>
-    createComponent(Counter, {
-      startingCount: 2
-    }),
-  document.getElementById("app")
-);
-
-delegateEvents(["click"]);
+```sh
+npm i solid-js @solidjs/web
+npm i -D babel-preset-solid
 ```
 
-</details>
-
-## More
+Add `babel-preset-solid` to your Babel config (or use Vite's Solid plugin), and set `tsconfig.json`:
 
-Check out our official [documentation](https://www.solidjs.com/guide) or browse some [examples](https://github.com/solidjs/solid/blob/main/documentation/resources/examples.md)
-
-## Browser Support
-
-SolidJS Core is committed to supporting the last 2 years of modern browsers including Firefox, Safari, Chrome and Edge (for desktop and mobile devices). We do not support IE or similar sunset browsers. For server environments, we support Node LTS and the latest Deno and Cloudflare Worker runtimes.
-
-<img src="https://saucelabs.github.io/images/opensauce/powered-by-saucelabs-badge-gray.svg?sanitize=true" alt="Testing Powered By SauceLabs" width="300"/>
-
-## Community
-
-Come chat with us on [Discord](https://discord.com/invite/solidjs)! Solid's creator and the rest of the core team are active there, and we're always looking for contributions.
+```json
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js"
+  }
+}
+```
 
-### Contributors
+Existing 1.x starter templates target 1.x — 2.0 starter templates are tracked at [solidjs/templates](https://github.com/solidjs/templates).
 
-<a href="https://github.com/solidjs/solid/graphs/contributors"><img src="https://opencollective.com/solid/contributors.svg?width=890&amp;button=false" style="max-width:100%;"></a>
+## For LLMs / AI assistants
 
-### Open Collective
+If you're an AI tool or model generating Solid 2.0 code: the public API differs from any Solid examples that predate 2.0. Read [`CHEATSHEET.md`](./CHEATSHEET.md) before generating — it lives inside this package (`node_modules/solid-js/CHEATSHEET.md`) for that reason. The bottom of the cheatsheet enumerates the specific patterns that changed from 1.x.
 
-Support us with a donation and help us continue our activities. [[Contribute](https://opencollective.com/solid)]
+The full migration guide is [`MIGRATION.md`](https://github.com/solidjs/solid/blob/next/documentation/solid-2.0/MIGRATION.md). Eight RFCs covering each subsystem (reactivity, control flow, stores, async, actions, DOM, dev-mode diagnostics) live alongside it under [`documentation/solid-2.0/`](https://github.com/solidjs/solid/tree/next/documentation/solid-2.0).
 
-<a href="https://opencollective.com/solid/backer/0/website" target="_blank"><img src="https://opencollective.com/solid/backer/0/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/1/website" target="_blank"><img src="https://opencollective.com/solid/backer/1/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/2/website" target="_blank"><img src="https://opencollective.com/solid/backer/2/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/3/website" target="_blank"><img src="https://opencollective.com/solid/backer/3/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/4/website" target="_blank"><img src="https://opencollective.com/solid/backer/4/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/5/website" target="_blank"><img src="https://opencollective.com/solid/backer/5/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/6/website" target="_blank"><img src="https://opencollective.com/solid/backer/6/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/7/website" target="_blank"><img src="https://opencollective.com/solid/backer/7/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/8/website" target="_blank"><img src="https://opencollective.com/solid/backer/8/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/9/website" target="_blank"><img src="https://opencollective.com/solid/backer/9/avatar.svg"></a>
-<a href="https://opencollective.com/solid/backer/10/website" target="_blank"><img src="https://opencollective.com/solid/backer/10/avatar.svg"></a>
+## Learn more
 
-### Sponsors
+- **Why Solid, key features, browser support, community, sponsors** — see the [repository README](https://github.com/solidjs/solid#readme).
+- **Full documentation** — [docs.solidjs.com](https://docs.solidjs.com).
+- **Examples** — [documentation/resources/examples.md](https://github.com/solidjs/solid/blob/next/documentation/resources/examples.md).
+- **Discord** — [discord.com/invite/solidjs](https://discord.com/invite/solidjs).
 
-Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/solid#sponsor)]
+---
 
-<a href="https://opencollective.com/solid/sponsor/0/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/0/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/1/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/1/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/2/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/2/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/3/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/3/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/4/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/4/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/5/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/5/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/6/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/6/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/7/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/7/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/8/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/8/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/9/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/9/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/10/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/10/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/11/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/11/avatar.svg"></a>
-<a href="https://opencollective.com/solid/sponsor/12/website" target="_blank"><img src="https://opencollective.com/solid/sponsor/12/avatar.svg"></a>
+_This is the npm package README for `solid-js`. The full repository README — including the monorepo layout, contributors, and sponsors — lives at [github.com/solidjs/solid](https://github.com/solidjs/solid#readme)._

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "solid-js",
-  "description": "A declarative JavaScript library for building user interfaces.",
-  "version": "2.0.0-beta.8",
+  "description": "Reactive JavaScript library for building user interfaces. Compiles JSX to real DOM with fine-grained signal-based updates — no virtual DOM.",
+  "version": "2.0.0-beta.9",
   "author": "Ryan Carniato",
   "license": "MIT",
   "homepage": "https://solidjs.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/solidjs/solid"
+    "url": "git+https://github.com/solidjs/solid.git",
+    "directory": "packages/solid"
   },
   "main": "./dist/server.cjs",
   "module": "./dist/server.js",
@@ -20,7 +21,8 @@
     "types",
     "types-cjs",
     "jsx-runtime.d.ts",
-    "package.json"
+    "package.json",
+    "CHEATSHEET.md"
   ],
   "exports": {
     ".": {
@@ -126,7 +128,7 @@
     "performance"
   ],
   "dependencies": {
-    "@solidjs/signals": "^2.0.0-beta.8",
+    "@solidjs/signals": "^2.0.0-beta.9",
     "csstype": "^3.1.0",
     "seroval": "~1.5.0",
     "seroval-plugins": "~1.5.0"

package/types/client/component.d.ts

@@ -63,7 +63,39 @@ export type ComponentProps<T extends ValidComponent> = T extends Component<infer
  * @example Component<{ref: Ref<Element>}>
  */
 export type Ref<T> = T | ((val: T) => void);
+/**
+ * Invokes a component, wrapping the call in `untrack` so that reactive reads
+ * inside the component body don't subscribe the parent computation. Compiled
+ * JSX uses this internally; manual calls are rarely needed unless authoring a
+ * custom JSX factory or renderer.
+ */
 export declare function createComponent<T extends Record<string, any>>(Comp: Component<T>, props: T): JSX.Element;
+/**
+ * Defines a code-split component. The returned component triggers its dynamic
+ * import on first render and suspends through any enclosing `<Loading>`
+ * boundary while the chunk is in flight. Call `.preload()` to start the
+ * import early (e.g. on hover).
+ *
+ * @param fn dynamic import returning the module's default export
+ * @param moduleUrl optional module URL used during hydration to look up
+ *   preloaded chunks; usually injected by the bundler integration
+ *
+ * @example
+ * ```tsx
+ * const Profile = lazy(() => import("./Profile"));
+ *
+ * function App() {
+ *   return (
+ *     <Loading fallback={<Spinner />}>
+ *       <Profile id="42" />
+ *     </Loading>
+ *   );
+ * }
+ *
+ * // Preload before the user clicks
+ * <button onMouseEnter={() => Profile.preload()}>Open profile</button>
+ * ```
+ */
 export declare function lazy<T extends Component<any>>(fn: () => Promise<{
     default: T;
 }>, moduleUrl?: string): T & {
@@ -72,4 +104,22 @@ export declare function lazy<T extends Component<any>>(fn: () => Promise<{
     }>;
     moduleUrl?: string;
 };
+/**
+ * Returns a stable id string that matches between server-rendered and
+ * client-hydrated trees. Use it for `<label for>`, `aria-labelledby`, and
+ * other attributes that need consistent ids across SSR.
+ *
+ * @example
+ * ```tsx
+ * function Field(props: { label: string }) {
+ *   const id = createUniqueId();
+ *   return (
+ *     <>
+ *       <label for={id}>{props.label}</label>
+ *       <input id={id} />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
 export declare function createUniqueId(): string;

package/types/client/core.d.ts

@@ -9,34 +9,101 @@ export type ContextProviderComponent<T> = FlowComponent<{
 }>;
 export interface Context<T> extends ContextProviderComponent<T> {
     id: symbol;
-    defaultValue: T;
+    defaultValue: T | undefined;
 }
 /**
- * Creates a Context to handle a state scoped for the children of a component
- * ```typescript
- * interface Context<T> {
- *   id: symbol;
- *   Provider: FlowComponent<{ value: T }>;
- *   defaultValue: T;
+ * Creates a Context for sharing state with descendants of a Provider in the
+ * component tree.
+ *
+ * The returned `Context` is itself a provider component — pass it a `value`
+ * prop to scope a value to its children. Read it inside descendants with
+ * `useContext`.
+ *
+ * Two forms:
+ *
+ * - **`createContext<T>()`** (default-less, the canonical form). Reading via
+ *   `useContext` outside an enclosing Provider throws `ContextNotFoundError`.
+ *   Use this for everything that carries reactive state — signals, stores,
+ *   `[state, actions]` tuples, services. The Provider is mandatory by
+ *   construction; the throw makes a missing Provider a loud bug instead of a
+ *   silent no-op. The annotation `<T>` is required because there is no value
+ *   to infer from.
+ * - **`createContext<T>(defaultValue)`** (default form). Reserved for the
+ *   narrow case of contexts whose value is a primitive with a meaningful
+ *   static fallback (theme, locale, frozen config). Outside any Provider,
+ *   `useContext` returns `defaultValue`.
+ *
+ * If you want truly app-wide state, **don't use Context** — a module-scope
+ * signal/store *is* a global. Context is for scoping state to a subtree;
+ * that's why a Provider is required.
+ *
+ * @param defaultValue optional default; only meaningful for primitive
+ *   fallbacks. Omit for any context carrying reactive state.
+ * @param options `{ name }` for debugging in development
+ * @returns a context object that doubles as its own provider component
+ *
+ * @example
+ * ```tsx
+ * // Reactive payload — default-less, throws if no Provider.
+ * type TodosCtx = readonly [Store<Todo[]>, TodoActions];
+ * const TodosContext = createContext<TodosCtx>();
+ *
+ * function App() {
+ *   return (
+ *     <TodosContext value={createTodos()}>
+ *       <TodoList />
+ *     </TodosContext>
+ *   );
+ * }
+ *
+ * function TodoList() {
+ *   const [todos, { addTodo }] = useContext(TodosContext); // typed as TodosCtx
+ *   // ...
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Primitive default — falls back to "light" outside a Provider.
+ * const ThemeContext = createContext<"light" | "dark">("light");
+ *
+ * function Button() {
+ *   const theme = useContext(ThemeContext); // "light" | "dark"
+ *   return <button class={theme}>Click</button>;
  * }
- * export function createContext<T>(
- *   defaultValue?: T,
- *   options?: { name?: string }
- * ): Context<T | undefined>;
  * ```
- * @param defaultValue optional default to inject into context
- * @param options allows to set a name in dev mode for debugging purposes
- * @returns The context that contains the Provider Component and that can be used with `useContext`
  *
  * @description https://docs.solidjs.com/reference/component-apis/create-context
  */
-export declare function createContext<T>(defaultValue?: undefined, options?: EffectOptions): Context<T | undefined>;
-export declare function createContext<T>(defaultValue: T, options?: EffectOptions): Context<T>;
+export declare function createContext<T>(defaultValue?: T, options?: EffectOptions): Context<T>;
 /**
- * Uses a context to receive a scoped state from a parent's Context.Provider
+ * Reads the current value of a context.
+ *
+ * - For `createContext<T>()` (default-less): returns the value from the
+ *   nearest enclosing Provider, or throws `ContextNotFoundError` if none is
+ *   mounted. Return type is `T` (no narrowing required).
+ * - For `createContext<T>(defaultValue)`: returns the value from the nearest
+ *   enclosing Provider, or `defaultValue` if none is mounted.
  *
- * @param context Context object made by `createContext`
- * @returns the current or `defaultValue`, if present
+ * In Solid, `useContext` is the canonical way to read context. There is no
+ * need for a wrapper hook that throws on missing Provider — the default-less
+ * form already does that, and its return type is `T`.
+ *
+ * @param context a context returned from `createContext`
+ * @returns the value provided by the nearest enclosing Provider, or the
+ *   default if one was supplied to `createContext`
+ * @throws `ContextNotFoundError` if no Provider is mounted and the context
+ *   was created without a default
+ *
+ * @example
+ * ```tsx
+ * const TodosContext = createContext<TodosCtx>();
+ *
+ * function TodoList() {
+ *   const [todos, { addTodo }] = useContext(TodosContext); // throws if no Provider
+ *   // ...
+ * }
+ * ```
  *
  * @description https://docs.solidjs.com/reference/component-apis/use-context
  */
@@ -47,10 +114,20 @@ export type ChildrenReturn = Accessor<ResolvedChildren> & {
     toArray: () => ResolvedJSXElement[];
 };
 /**
- * Resolves child elements to help interact with children
+ * Resolves a `children` accessor and exposes the result as an accessor with
+ * a `.toArray()` helper. Use this when a component needs to inspect or
+ * iterate over its children rather than just render them through.
  *
  * @param fn an accessor for the children
- * @returns a accessor of the same children, but resolved
+ * @returns an accessor of the resolved children, with `.toArray()` for iteration
+ *
+ * @example
+ * ```tsx
+ * function List(props: { children: JSX.Element }) {
+ *   const items = children(() => props.children);
+ *   return <ul>{items.toArray().map(item => <li>{item}</li>)}</ul>;
+ * }
+ * ```
  *
  * @description https://docs.solidjs.com/reference/component-apis/children
  */

package/types/client/flow.d.ts

@@ -41,7 +41,21 @@ export declare function Repeat<T extends JSX.Element>(props: {
     children: ((index: number) => T) | T;
 }): JSX.Element;
 /**
- * Conditionally render its children or an optional fallback component
+ * Conditionally renders its children when `when` is truthy, otherwise renders
+ * the optional `fallback`.
+ *
+ * The function-child form receives an accessor for the narrowed value — call
+ * it to read. Without `keyed` (default), the child is preserved across
+ * truthy values; with `keyed`, the child remounts whenever the value's
+ * identity changes.
+ *
+ * @example
+ * ```tsx
+ * <Show when={user()} fallback={<SignIn />}>
+ *   {u => <Greeting name={u().name} />}
+ * </Show>
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/components/show
  */
 export declare function Show<T, F extends ConditionalRenderCallback<T>>(props: {
@@ -74,12 +88,24 @@ export type MatchProps<T, F extends ConditionalRenderCallback<T> = ConditionalRe
     children: ConditionalRenderChildren<T, F>;
 };
 /**
- * Selects a content based on condition when inside a `<Switch>` control flow
- * ```typescript
- * <Match when={condition()}>
- *   <Content/>
- * </Match>
+ * A branch inside a `<Switch>`. The first `<Match>` whose `when` is truthy
+ * wins; remaining matches are skipped.
+ *
+ * Like `<Show>`, `<Match>` supports a function child that receives an
+ * accessor for the narrowed value.
+ *
+ * @example
+ * ```tsx
+ * <Switch fallback={<NotFound />}>
+ *   <Match when={user()}>
+ *     {u => <Profile name={u().name} />}
+ *   </Match>
+ *   <Match when={loading()}>
+ *     <Spinner />
+ *   </Match>
+ * </Switch>
  * ```
+ *
  * @description https://docs.solidjs.com/reference/components/switch-and-match
  */
 export declare function Match<T, F extends ConditionalRenderCallback<T>>(props: MatchProps<T, F>): JSX.Element;
@@ -103,14 +129,40 @@ export declare function Errored(props: {
     children: JSX.Element;
 }): JSX.Element;
 /**
- * Tracks all resources inside a component and renders a fallback until they are all resolved
- * ```typescript
- * const AsyncComponent = lazy(() => import('./component'));
+ * Renders a `fallback` while pending async reads inside the subtree settle.
+ *
+ * Any computation (`createMemo`, `createSignal(fn)`, `createStore(fn)`,
+ * `lazy(...)`, etc.) that throws because data isn't ready is caught by the
+ * nearest enclosing `<Loading>`. The boundary swaps to its `fallback` until
+ * every pending read has resolved, then renders the children.
+ *
+ * The optional `on` prop scopes the boundary so it ignores transitions
+ * caused by writes to other reactive sources — those transitions stay on the
+ * previous content (with `isPending()` flipping during the transition).
+ *
+ * Scope `<Loading>` around the data-dependent slot, not the surrounding
+ * shell. Wrapping layout chrome (header, nav, footer) in the same boundary
+ * as the data means revalidation replaces the entire screen with the
+ * fallback; rendering chrome outside the boundary keeps it stable while
+ * only the affordance flips.
  *
- * <Loading fallback={<LoadingIndicator />}>
- *   <AsyncComponent />
+ * @example
+ * ```tsx
+ * const Profile = lazy(() => import("./Profile"));
+ *
+ * <Loading fallback={<Spinner />}>
+ *   <Profile />
  * </Loading>
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Only show the fallback for transitions caused by writes to `route`.
+ * <Loading fallback={<Skeleton />} on={route}>
+ *   <Page />
+ * </Loading>
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/components/suspense
  */
 export declare function Loading(props: {