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

package/types/server/signals.d.ts

@@ -1,7 +1,7 @@
 export { createRoot, createOwner, runWithOwner, getOwner, isDisposed, onCleanup, getNextChildId, createContext, setContext, getContext, NotReadyError, NoOwnerError, ContextNotFoundError, isEqual, isWrappable, SUPPORTS_PROXY, enableExternalSource, enforceLoadingBoundary } from "@solidjs/signals";
 export { flatten } from "@solidjs/signals";
 export { snapshot, merge, omit, storePath, $PROXY, $REFRESH, $TRACK } from "@solidjs/signals";
-export type { Accessor, ComputeFunction, EffectFunction, EffectBundle, EffectOptions, ExternalSource, ExternalSourceConfig, ExternalSourceFactory, MemoOptions, NoInfer, SignalOptions, Setter, Signal, Owner, Maybe, Store, StoreSetter, StoreNode, NotWrappable, SolidStore, Merge, Omit, Context, ContextRecord, IQueue, StorePathRange, ArrayFilterFn, CustomPartial, Part, PathSetter } from "@solidjs/signals";
+export type { Accessor, ComputeFunction, EffectFunction, EffectBundle, EffectOptions, ExternalSource, ExternalSourceConfig, ExternalSourceFactory, MemoOptions, NoInfer, SignalOptions, Setter, Signal, Owner, Refreshable, Maybe, Store, StoreSetter, StoreNode, NotWrappable, SolidStore, Merge, Omit, Context, ContextRecord, IQueue, StorePathRange, ArrayFilterFn, CustomPartial, Part, PathSetter } from "@solidjs/signals";
 import type { Accessor, ComputeFunction, EffectFunction, EffectBundle, EffectOptions, MemoOptions, SignalOptions, Signal, Owner, Store, StoreSetter, Context } from "@solidjs/signals";
 import { sharedConfig, NoHydrateContext } from "./shared.js";
 interface ServerComputation<T = any> {
@@ -12,27 +12,46 @@ interface ServerComputation<T = any> {
     computed: boolean;
     disposed: boolean;
 }
+type SsrSourceMode = "server" | "hybrid" | "client";
+type ServerSsrOptions = {
+    deferStream?: boolean;
+    ssrSource?: SsrSourceMode;
+};
+type ServerClientMemoOptions<T> = Omit<MemoOptions<T>, "ssrSource"> & {
+    ssrSource: "client";
+};
+type ServerMemoOptions<T> = Omit<MemoOptions<T>, "ssrSource"> & {
+    ssrSource?: "server" | "hybrid";
+};
+type ServerClientSignalOptions<T> = Omit<SignalOptions<T>, "ssrSource"> & {
+    ssrSource: "client";
+};
+type ServerSignalOptions<T> = Omit<SignalOptions<T>, "ssrSource"> & {
+    ssrSource?: "server" | "hybrid";
+};
 export declare function getObserver(): ServerComputation<any> | null;
 export declare function createSignal<T>(): Signal<T | undefined>;
 export declare function createSignal<T>(value: Exclude<T, Function>, options?: SignalOptions<T>): Signal<T>;
-export declare function createSignal<T>(fn: ComputeFunction<undefined | NoInfer<T>, T>, options?: SignalOptions<T>): Signal<T>;
-export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, options?: MemoOptions<T>): Accessor<T>;
+export declare function createSignal<T>(fn: ComputeFunction<undefined | NoInfer<T>, T>, options: ServerClientSignalOptions<T>): Signal<T | undefined>;
+export declare function createSignal<T>(fn: ComputeFunction<undefined | NoInfer<T>, T>, options?: ServerSignalOptions<T>): Signal<T>;
+export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, options: ServerClientMemoOptions<T>): Accessor<T | undefined>;
+export declare function createMemo<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, options?: ServerMemoOptions<T>): Accessor<T>;
 export type PatchOp = [path: PropertyKey[]] | [path: PropertyKey[], value: any] | [path: PropertyKey[], value: any, insert: 1];
 export declare function createDeepProxy<T extends object>(target: T, patches: PatchOp[], basePath?: PropertyKey[]): T;
 export declare function createEffect<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, effect: EffectFunction<NoInfer<T>, T> | EffectBundle<NoInfer<T>, T>, options?: EffectOptions): void;
 export declare function createRenderEffect<T>(compute: ComputeFunction<undefined | NoInfer<T>, T>, effectFn: EffectFunction<NoInfer<T>, T>, options?: EffectOptions): void;
-export declare function createTrackedEffect(compute: () => void | (() => void), options?: EffectOptions): void;
+export declare function createTrackedEffect(compute: () => void | (() => void), options?: {
+    name?: string;
+}): void;
 export declare function createReaction(effectFn: EffectFunction<undefined> | EffectBundle<undefined>, options?: EffectOptions): (tracking: () => void) => void;
 export declare function createOptimistic<T>(): Signal<T | undefined>;
 export declare function createOptimistic<T>(value: Exclude<T, Function>, options?: SignalOptions<T>): Signal<T>;
-export declare function createOptimistic<T>(fn: ComputeFunction<undefined | NoInfer<T>, T>, options?: SignalOptions<T>): Signal<T>;
+export declare function createOptimistic<T>(fn: ComputeFunction<undefined | NoInfer<T>, T>, options: ServerClientSignalOptions<T>): Signal<T | undefined>;
+export declare function createOptimistic<T>(fn: ComputeFunction<undefined | NoInfer<T>, T>, options?: ServerSignalOptions<T>): Signal<T>;
 export declare function createStore<T extends object>(store: T | Store<T>): [get: Store<T>, set: StoreSetter<T>];
 export declare function createStore<T extends object>(fn: (store: T) => void | T | Promise<void | T>, store: Partial<T> | Store<T>): [get: Store<T>, set: StoreSetter<T>];
 export declare const createOptimisticStore: typeof createStore;
-export declare function createProjection<T extends object>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, initialValue: Partial<T>, options?: {
-    deferStream?: boolean;
-    ssrSource?: string;
-}): Store<T>;
+export declare function createProjection<T extends object>(fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>, initialValue: Partial<T>, options?: ServerSsrOptions): Store<T>;
 export declare function reconcile<T extends U, U extends object>(value: T): (state: U) => T;
 export declare function deep<T extends object>(store: Store<T>): Store<T>;
 export declare function mapArray<T, U>(list: Accessor<readonly T[] | undefined | null | false>, mapFn: (v: Accessor<T>, i: Accessor<number>) => U, options?: {
@@ -51,8 +70,9 @@ export declare function createErrorBoundary<U>(fn: () => any, fallback: (error:
 export declare function createLoadingBoundary(fn: () => any, fallback: () => any, options?: {
     on?: () => any;
 }): () => unknown;
+export type RevealOrder = "sequential" | "together" | "natural";
 export declare function createRevealOrder<T>(fn: () => T, _options?: {
-    together?: () => boolean;
+    order?: () => RevealOrder;
     collapsed?: () => boolean;
 }): T;
 export declare function untrack<T>(fn: () => T): T;

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

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

@@ -1,4 +1,5 @@
-import type { Accessor } from "@solidjs/signals";
+import type { Accessor, RevealOrder } from "@solidjs/signals";
+export type { RevealOrder };
 import type { JSX } from "../jsx.cjs";
 type NonZeroParams<T extends (...args: any[]) => any> = Parameters<T>["length"] extends 0 ? never : T;
 type ConditionalRenderCallback<T> = (item: Accessor<NonNullable<T>>) => JSX.Element;
@@ -40,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: {
@@ -73,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;
@@ -102,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).
  *
- * <Loading fallback={<LoadingIndicator />}>
- *   <AsyncComponent />
+ * 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.
+ *
+ * @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: {
@@ -117,26 +170,46 @@ export declare function Loading(props: {
     on?: any;
     children: JSX.Element;
 }): JSX.Element;
+export type RevealProps = {
+    order?: RevealOrder;
+    collapsed?: boolean;
+    children: JSX.Element;
+};
 /**
  * Coordinates the reveal timing of sibling `<Loading>` boundaries.
  *
- * - **Sequential** (default): boundaries reveal in DOM order as each resolves.
- * - **Together** (`together`): all boundaries wait until the group is ready, then reveal at once.
- * - **Collapsed** (`collapsed`, sequential only): only the frontier boundary shows its fallback;
- *   later boundaries produce nothing until their turn.
+ * The `order` prop picks the reveal policy:
+ * - `"sequential"` (default) — boundaries reveal in registration order; later boundaries
+ *   stay on their fallback until earlier ones resolve.
+ * - `"together"` — every direct slot stays on its fallback until the whole group is
+ *   "minimally ready" (every direct slot has its own first visible content available),
+ *   then the group releases in one cohesive reveal.
+ * - `"natural"` — each boundary reveals as its own data resolves. At the top level
+ *   this is equivalent to omitting `<Reveal>`; the mode exists for nesting, where
+ *   the group registers as a single composite slot in an enclosing `<Reveal>`.
+ *
+ * The `collapsed` prop is only consulted when `order="sequential"` (the default);
+ * it is ignored under `"together"` and `"natural"`. When set, tail boundaries past
+ * the frontier suppress their own fallback output.
+ *
+ * Nested `<Reveal>` groups compose: the inner group is one slot in the outer order
+ * and is held on its fallbacks until the outer releases the slot. Once released, the
+ * inner group runs its own `order` locally over whatever is still pending. There is
+ * no escape hatch — nesting under an outer group means participating in its ordering.
+ * See `documentation/solid-2.0/03-control-flow.md` for the full nesting matrix and the
+ * "minimally ready" definition per order.
  *
  * ```typescript
- * <Reveal>
+ * <Reveal order="sequential">
  *   <Loading fallback={<Skeleton />}><ProfileHeader /></Loading>
- *   <Loading fallback={<Skeleton />}><Posts /></Loading>
+ *   <Reveal order="natural">
+ *     <Loading fallback={<Skeleton />}><PostA /></Loading>
+ *     <Loading fallback={<Skeleton />}><PostB /></Loading>
+ *   </Reveal>
+ *   <Loading fallback={<Skeleton />}><Comments /></Loading>
  * </Reveal>
  * ```
  *
  * @description https://docs.solidjs.com/reference/components/reveal
  */
-export declare function Reveal(props: {
-    together?: boolean;
-    collapsed?: boolean;
-    children: JSX.Element;
-}): JSX.Element;
-export {};
+export declare function Reveal(props: RevealProps): JSX.Element;