@solidjs/web 2.0.0-experimental.9 → 2.0.0-rc.0

package/types/index.d.ts

@@ -1,45 +1,230 @@
 import { hydrate as hydrateCore } from "./client.js";
-import { JSX, ComponentProps, ValidComponent } from "solid-js";
+import { Component } from "solid-js";
+import type { JSX } from "./jsx.js";
 export * from "./client.js";
-export { For, Show, Suspense, Switch, Match, ErrorBoundary, merge as mergeProps } from "solid-js";
 export * from "./server-mock.js";
+export * from "./response.js";
+export type { JSX } from "./jsx.js";
+export { For, Show, Switch, Match, Errored, Loading, Repeat, Reveal, NoHydration, Hydration } from "solid-js";
+import { merge } from "solid-js";
+/**
+ * Compiler-emitted prop-spread helper. The JSX transform (in
+ * `dom-expressions`) emits `mergeProps(...)` calls when compiling prop
+ * spreads on components — it is *not* a user-facing API. Application code
+ * should import `merge` from `solid-js` directly.
+ *
+ * @internal
+ */
+export declare const mergeProps: typeof merge;
+/**
+ * Build-time constant indicating whether code is running on the server. This
+ * client entry sets it to `false`; the matching server entry (`@solidjs/web`
+ * resolved through the `solid` server export condition) sets it to `true`.
+ *
+ * Bundlers can dead-code-eliminate branches gated on `isServer`, so guarding
+ * browser-only code with `if (!isServer) {…}` keeps it out of the SSR bundle
+ * entirely.
+ *
+ * @example
+ * ```ts
+ * import { isServer } from "@solidjs/web";
+ *
+ * if (!isServer) {
+ *   // Browser-only: tree-shaken out of the SSR bundle.
+ *   window.addEventListener("resize", onResize);
+ * }
+ * ```
+ */
 export declare const isServer: boolean;
-export declare const isDev: boolean;
-export declare const hydrate: typeof hydrateCore;
 /**
- * Renders components somewhere else in the DOM
+ * Build-time constant indicating whether code is running in a dev build.
+ * Replaced statically (`_SOLID_DEV_`) by the bundler integration, so guards
+ * like `if (isDev) {…}` are stripped from production builds.
  *
- * Useful for inserting modals and tooltips outside of an cropping layout. If no mount point is given, the portal is inserted in document.body; it is wrapped in a `<div>` unless the target is document.head or `isSVG` is true. setting `useShadow` to true places the element in a shadow root to isolate styles.
+ * Use this to gate dev-only diagnostics, warnings, or expensive invariants
+ * that should never ship to production.
  *
- * @description https://docs.solidjs.com/reference/components/portal
+ * @example
+ * ```ts
+ * import { isDev } from "@solidjs/web";
+ *
+ * if (isDev) {
+ *   console.warn("debug-only path");
+ * }
+ * ```
  */
-export declare function Portal<T extends boolean = false, S extends boolean = false>(props: {
-    mount?: Element;
-    children: JSX.Element;
-}): Text;
+export declare const isDev: boolean;
+type MountableElement = Element | Document | ShadowRoot | DocumentFragment | Node;
+export type IntrinsicElement = Extract<keyof JSX.IntrinsicElements, string>;
+export type ValidComponent = IntrinsicElement | Component<any> | (string & {});
+export type ComponentProps<T extends ValidComponent> = T extends Component<infer P> ? P : T extends keyof JSX.IntrinsicElements ? JSX.IntrinsicElements[T] : Record<string, unknown>;
 export type DynamicProps<T extends ValidComponent, P = ComponentProps<T>> = {
     [K in keyof P]: P[K];
 } & {
-    component: T | undefined;
+    component: T | null | undefined | false;
 };
 /**
- * Renders an arbitrary component or element with the given props
+ * Renders a component tree into a DOM element. Returns a dispose function
+ * that tears the tree down and cleans up reactive scopes when called.
+ *
+ * @example
+ * ```tsx
+ * import { render } from "@solidjs/web";
  *
- * This is a lower level version of the `Dynamic` component, useful for
- * performance optimizations in libraries. Do not use this unless you know
- * what you are doing.
- * ```typescript
- * const element = () => multiline() ? 'textarea' : 'input';
- * createDynamic(element, { value: value() });
+ * const dispose = render(() => <App />, document.getElementById("root")!);
+ *
+ * // Later, to unmount:
+ * dispose();
  * ```
- * @description https://docs.solidjs.com/reference/components/dynamic
+ *
+ * @remarks
+ * The top-level insert is queued via `insertOptions: { schedule: true }` so
+ * its initial DOM attach goes through the effect queue rather than executing
+ * inline. This lets the mount participate in transitions: if an uncaught
+ * async read surfaces during the initial render (no `Loading` ancestor
+ * absorbs it), the mount is held by the transition and attaches atomically
+ * once all pending settles. On the no-async happy path the tail `flush()`
+ * drains the queued callback so the attach is synchronous by the time
+ * `render()` returns. The dev enforcement window scopes
+ * `ASYNC_OUTSIDE_LOADING_BOUNDARY` to the initial mount only.
  */
-export declare function createDynamic<T extends ValidComponent>(component: () => T | undefined, props: ComponentProps<T>): JSX.Element;
+export declare function render(code: () => JSX.Element, element: MountableElement, init?: unknown, options?: {
+    renderId?: string;
+}): () => void;
 /**
- * Renders an arbitrary custom or native component and passes the other props
- * ```typescript
- * <Dynamic component={multiline() ? 'textarea' : 'input'} value={value()} />
+ * Resumes a server-rendered tree on the client, attaching event listeners
+ * and reactive bindings without reconstructing the DOM. Returns a `dispose`
+ * function that tears down reactive scopes (DOM nodes are left in place).
+ *
+ * Use this when the page HTML was produced by `renderToString` or
+ * `renderToStream`. For client-only apps, use `render` instead.
+ *
+ * Pass `options.renderId` to hydrate one of multiple roots emitted by a
+ * server render that used the same id.
+ *
+ * @example
+ * ```tsx
+ * import { hydrate } from "@solidjs/web";
+ *
+ * hydrate(() => <App />, document.getElementById("root")!);
  * ```
+ */
+export declare const hydrate: typeof hydrateCore;
+/**
+ * Renders its children into a different part of the DOM (modal roots,
+ * tooltips, layers that need to escape an `overflow: hidden` ancestor).
+ *
+ * If `mount` is omitted, the portal attaches to `document.body`. The portal
+ * still participates in the parent's reactive scope and disposes when the
+ * parent does.
+ *
+ * Portals are client-only islands: the server renders nothing for them, and
+ * under hydration the children render fresh once hydration settles. Async
+ * read inside a portal therefore starts on the client — data that should be
+ * fetched on the server belongs above the portal (hoist the read, not the
+ * render), and async UI inside one wants its own `<Loading>` boundary.
+ *
+ * @example
+ * ```tsx
+ * <Portal mount={document.getElementById("modal-root")!}>
+ *   <Dialog />
+ * </Portal>
+ * ```
+ *
+ * @description https://docs.solidjs.com/reference/components/portal
+ */
+export declare function Portal(props: {
+    mount?: Element;
+    children: JSX.Element;
+}): JSX.Element;
+export declare function dynamic<T extends ValidComponent>(source: () => T | Promise<T> | null | undefined | false): Component<ComponentProps<T>>;
+/**
+ * Renders an arbitrary custom or native component and forwards the other
+ * props. JSX form of `dynamic()` — same primitive, picked at the JSX site.
+ *
+ * @example
+ * ```tsx
+ * <Dynamic
+ *   component={multiline() ? RichTextEditor : "input"}
+ *   value={value()}
+ *   onInput={onInput}
+ * />
+ * ```
+ *
  * @description https://docs.solidjs.com/reference/components/dynamic
  */
 export declare function Dynamic<T extends ValidComponent>(props: DynamicProps<T>): JSX.Element;
+/**
+ * Wraps a dynamically imported component so it renders only in the browser.
+ * The server renders `props.fallback` (and nothing else); the client shows
+ * the fallback until the import resolves and the tree has mounted, then
+ * swaps the real component in.
+ *
+ * Unlike `lazy()`, this avoids Suspense entirely and never server-renders
+ * the wrapped component — only the fallback — so the component participates
+ * in no hydration asset manifest and its code is guaranteed to never run on
+ * the server (safe for browser-only libraries touching `window`, DOM
+ * measurement, etc.). The mount gate keeps hydration safe: during hydration
+ * the fallback is rendered exactly as the server did, and the swap happens
+ * only after settle, so there is no mismatch.
+ *
+ * By default the import starts as soon as `clientOnly` is called (module
+ * load); pass `{ lazy: true }` to defer the import to the component's first
+ * render.
+ *
+ * @example
+ * ```tsx
+ * const Chart = clientOnly(() => import("./Chart.jsx"));
+ * // <Chart fallback={<div>Loading chart…</div>} data={data()} />
+ * ```
+ */
+export declare function clientOnly<T extends Component<any>>(fn: () => Promise<{
+    default: T;
+}>, options?: {
+    lazy?: boolean;
+}, _moduleUrl?: string): Component<ComponentProps<T> & {
+    fallback?: JSX.Element;
+}>;
+/**
+ * Declares the HTTP response status (and optional status text) for the
+ * lifetime of the current reactive scope during SSR — call it bare in a
+ * component or reactive-scope body where the status is decided (a 404
+ * route, an error fallback). Client build: a no-op — the response head was
+ * sent long ago.
+ *
+ * Naming note — this is a scope-tied *declaration*, not a mutation: "while
+ * this reactive scope is live, the response has this status." Solid
+ * reserves `set*` verbs for event-time mutation; like
+ * `createSignal`/`onCleanup` this is called in scope bodies and un-declares
+ * on scope disposal.
+ *
+ * Retraction semantics (server): the write snapshots the previous
+ * `event.response` status at write time and restores it when the owning
+ * scope is disposed — so a boundary that errored, declared a status, and
+ * then recovered retracts its write instead of stomping a status a
+ * surviving part of the tree legitimately set. Once the integration marks
+ * the response head `committed` (head derived/sent), writes and
+ * retractions are no-ops.
+ */
+export declare function httpStatus(_code: number, _text?: string): void;
+/**
+ * Declares an HTTP response header (or with `append`, appends to one) for
+ * the lifetime of the current reactive scope during SSR — call it bare in a
+ * component or reactive-scope body. Client build: a no-op — the response
+ * head was sent long ago.
+ *
+ * Naming note — this is a scope-tied *declaration*, not a mutation: "while
+ * this reactive scope is live, the response has this header." Solid
+ * reserves `set*` verbs for event-time mutation; like
+ * `createSignal`/`onCleanup` this is called in scope bodies and un-declares
+ * on scope disposal.
+ *
+ * Retraction semantics (server): the header's prior value is snapshotted at
+ * write time and restored when the owning scope is disposed (deleted if
+ * there was none) — a boundary that errors or recovers retracts its writes.
+ * Once the integration marks the response head `committed` (head
+ * derived/sent), writes and retractions are no-ops.
+ */
+export declare function httpHeader(_name: string, _value: string, _options?: {
+    append?: boolean;
+}): void;

package/types/jsx-properties.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared type-level helpers used to derive `prop:*` attribute typings from
+ * DOM element interfaces (e.g. `HTMLInputElement`, `HTMLButtonElement`).
+ *
+ * The wrapping of each value (`FunctionMaybe<T>` in `jsx-h.d.ts` vs. the
+ * raw value in `jsx.d.ts`) is applied by each consumer when composing its
+ * own `Properties<T>` mapped type. That way this file stays identical in
+ * both reactive and non-reactive contexts and only needs to exist once.
+ *
+ * originally from
+ * @url https://github.com/potahtml/pota
+ */
+
+/** Base-class properties shared by all elements — skipped from `prop:*`. */
+export type SkipPropsFrom = HTMLUnknownElement & HTMLElement & Element & Node;
+
+/**
+ * Value types allowed on a `prop:*`. Primitives plus the writable
+ * non-primitive DOM-object props worth exposing:
+ *
+ * - `HTMLMediaElement.srcObject`
+ * - `HTMLButtonElement.popoverTargetElement` / `commandForElement` (and the same via
+ *   `PopoverTargetAttributes` mixin on `HTMLInputElement`)
+ */
+export type PropValue =
+  | string
+  | number
+  | boolean
+  | null
+  | MediaStream
+  | MediaSource
+  | Blob
+  | File
+  | Date
+  | Element;
+
+/**
+ * Ergonomics widening for emitted `prop:*` value types:
+ *
+ * - general `string` → `string | number` (HTML coerces numbers)
+ * - string literal unions (`'on' | 'off'`) stay exact, so users still get autocomplete /
+ *   narrowing
+ * - other types pass through unchanged
+ */
+type WidenString<V> = string extends V ? string | number : V;
+export type WidenPropValue<V> = [V] extends [string] ? WidenString<V> : V;
+
+/**
+ * Structurally identical → `Y`; distinct → `N`. Used by `IsReadonlyKey` to detect
+ * readonly keys by comparing `Pick<T, K>` with `Readonly<Pick<T, K>>`.
+ */
+export type IfEquals<A, B, Y = unknown, N = never> =
+  (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? Y : N;
+
+/**
+ * True when `K` is readonly on `T`. Singleton-constant properties (e.g.
+ * `tagName: "INPUT"`, `nodeType: 1`) are always `readonly` in `lib.dom.d.ts`, so this
+ * single check covers both readonly and singleton-literal cases.
+ */
+export type IsReadonlyKey<T, K extends keyof T> = IfEquals<
+  Pick<T, K>,
+  Readonly<Pick<T, K>>,
+  true,
+  false
+>;
+
+/**
+ * Resolves to the `prop:K` string literal when `K` is a writable, element-specific
+ * property suitable for a `prop:*` attribute; otherwise resolves to `never` so the
+ * key is filtered out of the resulting mapped type.
+ *
+ * Filters out:
+ *
+ * - base-class keys (via `SkipPropsFrom`)
+ * - aria-* keys (already typed via `AriaAttributes`)
+ * - readonly keys
+ * - keys whose value types fall outside `PropValue`
+ * - the generic `string` index signature (e.g. `HTMLFormElement[name: string]: any`),
+ *   which would otherwise shadow every key with an `any`-typed `prop:*`
+ */
+export type PropKey<T, K extends keyof T> = K extends keyof SkipPropsFrom
+  ? never
+  : K extends string
+    ? string extends K
+      ? never
+      : K extends `aria${string}`
+        ? never
+        : T[K] extends PropValue
+          ? IsReadonlyKey<T, K> extends true
+            ? never
+            : `prop:${K}`
+          : never
+    : never;