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

package/types-cjs/client/core.d.cts

@@ -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-cjs/client/flow.d.cts

@@ -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: {