@solidjs/web 2.0.0-beta.3 → 2.0.0-beta.30

package/types-cjs/frames/serializer.d.cts

@@ -0,0 +1,157 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+/**
+ * Seroval's node shape — the intermediate representation `serializeJSON`
+ * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
+ */
+export type { SerovalNode };
+
+/**
+ * A Seroval plugin usable with the web serializers — teaches the codec how
+ * to encode/decode a custom value type. Supply matching plugins on both
+ * peers of a transport.
+ */
+export type SerializerPlugin = Plugin<any, any>;
+
+/**
+ * Baseline plugin set for serializing web-platform values (AbortSignal,
+ * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
+ * Applied by every serializer in this module; custom plugins compose ahead
+ * of it via `resolveSerializerPlugins`.
+ */
+export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+
+/**
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
+ * first so they can shadow a default for values both would match. Returns a
+ * fresh array; the defaults are never mutated. Useful when handing a full
+ * plugin list to another serialization layer.
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+/** Options for `createSerializer`. */
+export interface WebSerializerOptions {
+  /** Name of the global object the emitted scripts write resolved values into. */
+  globalIdentifier: string;
+  /** Cross-reference scope id, for isolating multiple streams on one page. */
+  scopeId?: string;
+  /**
+   * Seroval feature bitflags to exclude from output. Defaults to disabling
+   * post-ES2017 features (AggregateError, BigInt typed arrays). Outside
+   * development, `Error.prototype.stack` is additionally stripped on top of
+   * any override — serialized stacks leak server paths to the client.
+   */
+  disabledFeatures?: number;
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
+  plugins?: SerializerPlugin[];
+  /** Receives each emitted script chunk. */
+  onData: (result: string) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy. Emits JavaScript chunks (through
+ * `onData`) that reconstruct the values under `globalIdentifier` when
+ * evaluated — the script-injection form of serialization renderers build
+ * on. For a JSON-based wire codec (no eval on the receiving side), use
+ * `serializeJSON` / `createJSONDeserializer` instead.
+ */
+export function createSerializer(options: WebSerializerOptions): Serializer;
+
+/**
+ * Options for `createHydrationSerializer` — `WebSerializerOptions` minus
+ * the knobs hydration pins (`globalIdentifier`, `disabledFeatures`).
+ * @internal
+ */
+export type HydrationSerializerOptions = Omit<
+  WebSerializerOptions,
+  "globalIdentifier" | "disabledFeatures"
+>;
+
+/**
+ * Renderer primitive — the serializer SSR uses for hydration output. Pins
+ * the hydration global (`_$HY.r`) and feature policy; only the wiring
+ * options (callbacks, scope, extra plugins) are configurable. Not meant
+ * for hand-written code — custom serialization should use
+ * `createSerializer` or the JSON codec.
+ * @internal
+ */
+export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+
+/**
+ * Renderer primitive — returns the cross-reference bootstrap script SSR
+ * emits ahead of hydration data for a render scope. Not meant for
+ * hand-written code.
+ * @internal
+ */
+export function getLocalHeaderScript(id?: string): string;
+
+// ---- JSON codec (server function transports) ----
+
+/**
+ * Options shared by both halves of the JSON codec. All of them must match
+ * on the serializing and deserializing peer or payloads will not
+ * round-trip — for server functions, set them once through the
+ * client/server `codec` config option.
+ */
+export interface JSONCodecOptions {
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
+  plugins?: SerializerPlugin[];
+  /**
+   * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+   * (payloads may come from an untrusted peer). Must match on both peers.
+   * Outside development, the encoding side additionally strips
+   * `Error.prototype.stack` on top of any override — serialized stacks leak
+   * server paths to the client. Decoding stays permissive, so payloads from
+   * a development peer still round-trip.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+/** Options for `serializeJSON`. */
+export interface JSONSerializeOptions extends JSONCodecOptions {
+  /**
+   * Receives each serialized node; `initial` is true for the first chunk
+   * (the source value itself). Async values produce additional chunks as
+   * they resolve.
+   */
+  onParse: (node: SerovalNode, initial: boolean) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through `onParse` —
+ * the encoding half of the eval-free JSON codec (RPC-style transports;
+ * the deserializing peer needs no script evaluation, so CSP-safe). Wire
+ * framing of the nodes is the transport's concern. Returns a cancel
+ * function that aborts pending async serialization.
+ */
+export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
+ * between chunks resolve through state shared across calls, so all chunks
+ * from one stream must go through the same deserializer instance. The first
+ * chunk's return value is the decoded source value; feeding later chunks
+ * settles the async values referenced inside it.
+ */
+export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
+
+/**
+ * A resident, response-scoped decode table over the keyed JSON codec: apply
+ * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
+ * `resolve`. The frames client host wires one per response
+ * (`applyData: c => table.apply(c)`).
+ */
+export interface JSONDataTable {
+  apply(chunk: { key?: string; node?: unknown; initial?: boolean }): void;
+  resolve<T = unknown>(ref: { $ref: string }): T;
+}
+export function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;

package/types-cjs/frames/server.d.cts

@@ -0,0 +1,30 @@
+import type { Element as SolidElement } from "solid-js";
+/**
+ * A client position in a server component: a prop the server renders (as JSX
+ * or by calling it) where client-owned markup belongs. `P` is the client
+ * component's own props, so a server component can reference the client
+ * component's type directly instead of restating it.
+ *
+ * Arguments are classified by VALUE, not by name — any prop may carry any of
+ * these:
+ *
+ * - primitives ride the chunk;
+ * - server JSX streams as a nested region (html once, never data);
+ * - anything else serializes as a data record.
+ *
+ * Async server JSX in an argument needs its own boundary: the region is
+ * emitted as one finished string, so a bare async read has no fallback to
+ * show and no fragment to reveal into.
+ *
+ * `$key` names the occurrence so client state follows an entity across
+ * responses rather than being positional — the slot-level analogue of `For`'s
+ * `keyed`, for when references can't carry identity because every response
+ * re-creates everything. It is occurrence identity, not client data: it is
+ * stripped before the client component sees its props. Positional identity is
+ * the right default; `$key` matters when a live list reorders.
+ */
+export type Slot<P = {}> = (props: P & {
+    $key?: string | number;
+}) => SolidElement;
+export { renderToFrameStream, renderServerComponent, serverComponentResponse, frameTransformResult, frameTransformFlightResult, createFrameSink, frameTransformDirectResult, ServerComponentPlugin, SERVER_COMPONENT_BOOTSTRAP } from "./frame-sink.cjs";
+export { FRAME_STREAM_HEADER, isFrameStreamResponse } from "./frame-transport.cjs";

package/types-cjs/index.d.cts

@@ -0,0 +1,231 @@
+import { hydrate as hydrateCore } from "./client.cjs";
+import { Component } from "solid-js";
+import type { JSX } from "./jsx.cjs";
+export * from "./client.cjs";
+export * from "./server-mock.cjs";
+export * from "./response.cjs";
+export type { JSX } from "./jsx.cjs";
+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;
+/**
+ * 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.
+ *
+ * Use this to gate dev-only diagnostics, warnings, or expensive invariants
+ * that should never ship to production.
+ *
+ * @example
+ * ```ts
+ * import { isDev } from "@solidjs/web";
+ *
+ * if (isDev) {
+ *   console.warn("debug-only path");
+ * }
+ * ```
+ */
+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 | null | undefined | false;
+};
+/**
+ * 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";
+ *
+ * const dispose = render(() => <App />, document.getElementById("root")!);
+ *
+ * // Later, to unmount:
+ * dispose();
+ * ```
+ *
+ * @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 render(code: () => JSX.Element, element: MountableElement, init?: unknown, options?: {
+    renderId?: string;
+}): () => void;
+/**
+ * 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`,
+ * `renderToStringAsync`, 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-cjs/jsx-properties.d.cts

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