solid-js 2.0.0-beta.1 → 2.0.0-beta.10

package/types/client/flow.d.ts

@@ -1,10 +1,18 @@
-import type { Accessor } from "@solidjs/signals";
-import type { JSX } from "../jsx.js";
+import type { Accessor, RevealOrder } from "@solidjs/signals";
+export type { RevealOrder };
+import type { Element as SolidElement } from "../types.js";
+type NonZeroParams<T extends (...args: any[]) => any> = Parameters<T>["length"] extends 0 ? never : T;
+type ConditionalRenderCallback<T> = (item: Accessor<NonNullable<T>>) => SolidElement;
+type ConditionalRenderChildren<T, F extends ConditionalRenderCallback<T> = ConditionalRenderCallback<T>> = SolidElement | NonZeroParams<F>;
 /**
- * Creates a list of elements from a list
+ * Creates a list of elements from a list.
  *
- * it receives a map function as its child that receives list element and index accessors and returns a JSX-Element; if the list is empty, an optional fallback is returned:
- * ```typescript
+ * Receives a map function as its child that takes list element and index
+ * accessors and returns a JSX element; if the list is empty, an optional
+ * `fallback` is rendered instead.
+ *
+ * @example
+ * ```tsx
  * <For each={items} fallback={<div>No items</div>}>
  *   {(item, index) => <div data-index={index()}>{item()}</div>}
  * </For>
@@ -12,17 +20,20 @@ import type { JSX } from "../jsx.js";
  *
  * @description https://docs.solidjs.com/reference/components/for
  */
-export declare function For<T extends readonly any[], U extends JSX.Element>(props: {
+export declare function For<T extends readonly any[], U extends SolidElement>(props: {
     each: T | undefined | null | false;
-    fallback?: JSX.Element;
+    fallback?: SolidElement;
     keyed?: boolean | ((item: T[number]) => any);
     children: (item: Accessor<T[number]>, index: Accessor<number>) => U;
-}): JSX.Element;
+}): SolidElement;
 /**
- * Creates a list elements from a count
+ * Creates a list of elements from a count.
+ *
+ * Receives a map function as its child that takes the index and returns a JSX
+ * element; if the count is zero, an optional `fallback` is rendered instead.
  *
- * it receives a map function as its child that receives the index and returns a JSX-Element; if the list is empty, an optional fallback is returned:
- * ```typescript
+ * @example
+ * ```tsx
  * <Repeat count={items.length} fallback={<div>No items</div>}>
  *   {(index) => <div data-index={index}>{items[index]}</div>}
  * </Repeat>
@@ -30,25 +41,43 @@ export declare function For<T extends readonly any[], U extends JSX.Element>(pro
  *
  * @description https://docs.solidjs.com/reference/components/repeat
  */
-export declare function Repeat<T extends JSX.Element>(props: {
+export declare function Repeat<T extends SolidElement>(props: {
     count: number;
     from?: number | undefined;
-    fallback?: JSX.Element;
+    fallback?: SolidElement;
     children: ((index: number) => T) | T;
-}): JSX.Element;
+}): SolidElement;
 /**
- * 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>(props: {
+export declare function Show<T, F extends ConditionalRenderCallback<T>>(props: {
     when: T | undefined | null | false;
     keyed?: boolean;
-    fallback?: JSX.Element;
-    children: JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element);
-}): JSX.Element;
+    fallback?: SolidElement;
+    children: ConditionalRenderChildren<T, F>;
+}): SolidElement;
 /**
- * Switches between content based on mutually exclusive conditions
- * ```typescript
+ * Switches between content based on mutually exclusive conditions. Renders
+ * the first `<Match>` whose `when` is truthy; falls back to `fallback` when
+ * none match.
+ *
+ * @example
+ * ```tsx
  * <Switch fallback={<FourOhFour />}>
  *   <Match when={state.route === 'home'}>
  *     <Home />
@@ -58,43 +87,148 @@ export declare function Show<T>(props: {
  *   </Match>
  * </Switch>
  * ```
+ *
  * @description https://docs.solidjs.com/reference/components/switch-and-match
  */
 export declare function Switch(props: {
-    fallback?: JSX.Element;
-    children: JSX.Element;
-}): JSX.Element;
-export type MatchProps<T> = {
+    fallback?: SolidElement;
+    children: SolidElement;
+}): SolidElement;
+export type MatchProps<T, F extends ConditionalRenderCallback<T> = ConditionalRenderCallback<T>> = {
     when: T | undefined | null | false;
     keyed?: boolean;
-    children: JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element);
+    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>(props: MatchProps<T>): JSX.Element;
+export declare function Match<T, F extends ConditionalRenderCallback<T>>(props: MatchProps<T, F>): SolidElement;
 /**
- * Catches uncaught errors inside components and renders a fallback content
+ * Catches uncaught errors inside its subtree and renders fallback content
+ * instead. The `fallback` prop can be a JSX element, or a callback that
+ * receives the error and a `reset()` function for retry affordances.
  *
- * Also supports a callback form that passes the error and a reset function:
- * ```typescript
- * <Errored fallback={
- *   (err, reset) => <div onClick={reset}>Error: {err.toString()}</div>
- * }>
+ * Errors thrown from the fallback itself can be caught by a parent
+ * `<Errored>`.
+ *
+ * @example
+ * ```tsx
+ * <Errored fallback={(err, reset) => (
+ *   <div onClick={reset}>Error: {err.toString()}</div>
+ * )}>
  *   <MyComp />
  * </Errored>
  * ```
- * Errors thrown from the fallback can be caught by a parent Errored
  *
  * @description https://docs.solidjs.com/reference/components/error-boundary
  */
 export declare function Errored(props: {
-    fallback: JSX.Element | ((err: any, reset: () => void) => JSX.Element);
-    children: JSX.Element;
-}): JSX.Element;
+    fallback: SolidElement | ((err: any, reset: () => void) => SolidElement);
+    children: SolidElement;
+}): SolidElement;
+/**
+ * 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.
+ *
+ * @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: {
+    fallback?: SolidElement;
+    on?: any;
+    children: SolidElement;
+}): SolidElement;
+export type RevealProps = {
+    order?: RevealOrder;
+    collapsed?: boolean;
+    children: SolidElement;
+};
+/**
+ * Coordinates the reveal timing of sibling `<Loading>` boundaries.
+ *
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * // Default order is "sequential"; the inner group composes as one slot
+ * // and runs its own "natural" order locally once the outer releases it.
+ * <Reveal>
+ *   <Loading fallback={<Skeleton />}><ProfileHeader /></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: RevealProps): SolidElement;