npm - @jasonshimmy/custom-elements-runtime - Versions diffs - 2.8.2 → 3.1.0 - Mend

@jasonshimmy/custom-elements-runtime 2.8.2 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (99) hide show

package/README.md +223 -73
package/dist/css-utils-Cg4o1MqY.js +643 -0
package/dist/css-utils-Cg4o1MqY.js.map +1 -0
package/dist/css-utils-RqkyBWft.cjs +576 -0
package/dist/css-utils-RqkyBWft.cjs.map +1 -0
package/dist/custom-elements-runtime.cjs.js +3 -3
package/dist/custom-elements-runtime.cjs.js.map +1 -1
package/dist/custom-elements-runtime.dom-jit-css.cjs.js +7 -0
package/dist/custom-elements-runtime.dom-jit-css.cjs.js.map +1 -0
package/dist/custom-elements-runtime.dom-jit-css.es.js +136 -0
package/dist/custom-elements-runtime.dom-jit-css.es.js.map +1 -0
package/dist/custom-elements-runtime.es.js +105 -97
package/dist/custom-elements-runtime.es.js.map +1 -1
package/dist/custom-elements-runtime.event-bus.cjs.js +1 -1
package/dist/custom-elements-runtime.event-bus.cjs.js.map +1 -1
package/dist/custom-elements-runtime.event-bus.es.js +62 -46
package/dist/custom-elements-runtime.event-bus.es.js.map +1 -1
package/dist/custom-elements-runtime.jit-css.cjs.js +2 -0
package/dist/custom-elements-runtime.jit-css.cjs.js.map +1 -0
package/dist/custom-elements-runtime.jit-css.es.js +37 -0
package/dist/custom-elements-runtime.jit-css.es.js.map +1 -0
package/dist/custom-elements-runtime.router.cjs.js +20 -20
package/dist/custom-elements-runtime.router.cjs.js.map +1 -1
package/dist/custom-elements-runtime.router.es.js +472 -458
package/dist/custom-elements-runtime.router.es.js.map +1 -1
package/dist/custom-elements-runtime.ssr-middleware.cjs.js +2 -0
package/dist/custom-elements-runtime.ssr-middleware.cjs.js.map +1 -0
package/dist/custom-elements-runtime.ssr-middleware.es.js +63 -0
package/dist/custom-elements-runtime.ssr-middleware.es.js.map +1 -0
package/dist/custom-elements-runtime.ssr.cjs.js +3 -1
package/dist/custom-elements-runtime.ssr.cjs.js.map +1 -1
package/dist/custom-elements-runtime.ssr.es.js +137 -24
package/dist/custom-elements-runtime.ssr.es.js.map +1 -1
package/dist/custom-elements-runtime.store.cjs.js +1 -1
package/dist/custom-elements-runtime.store.cjs.js.map +1 -1
package/dist/custom-elements-runtime.store.es.js +21 -16
package/dist/custom-elements-runtime.store.es.js.map +1 -1
package/dist/custom-elements-runtime.transitions.cjs.js +1 -1
package/dist/custom-elements-runtime.transitions.cjs.js.map +1 -1
package/dist/custom-elements-runtime.transitions.es.js +279 -7
package/dist/custom-elements-runtime.transitions.es.js.map +1 -1
package/dist/custom-elements-runtime.vite-plugin.cjs.js +2 -0
package/dist/custom-elements-runtime.vite-plugin.cjs.js.map +1 -0
package/dist/custom-elements-runtime.vite-plugin.es.js +105 -0
package/dist/custom-elements-runtime.vite-plugin.es.js.map +1 -0
package/dist/dom-jit-css.d.ts +66 -0
package/dist/event-bus.d.ts +3 -1
package/dist/hooks-B50HhrHh.cjs +6 -0
package/dist/hooks-B50HhrHh.cjs.map +1 -0
package/dist/hooks-Cze3o-F7.js +1462 -0
package/dist/hooks-Cze3o-F7.js.map +1 -0
package/dist/index.d.ts +6 -3
package/dist/jit-css.d.ts +30 -0
package/dist/namespace-helpers-D4wC2-qA.js +61 -0
package/dist/namespace-helpers-D4wC2-qA.js.map +1 -0
package/dist/namespace-helpers-ckeEOxpR.cjs +2 -0
package/dist/namespace-helpers-ckeEOxpR.cjs.map +1 -0
package/dist/router/matcher.d.ts +14 -0
package/dist/router/types.d.ts +4 -2
package/dist/runtime/component/factory.d.ts +16 -2
package/dist/runtime/css-utils.d.ts +33 -0
package/dist/runtime/discovery-state.d.ts +3 -0
package/dist/runtime/hooks.d.ts +78 -0
package/dist/runtime/hydration.d.ts +33 -0
package/dist/runtime/jit-hooks.d.ts +28 -0
package/dist/runtime/render-bridge.d.ts +37 -0
package/dist/runtime/scheduler.d.ts +3 -4
package/dist/runtime/secure-expression-evaluator.d.ts +0 -1
package/dist/runtime/ssr-context.d.ts +45 -0
package/dist/runtime/style.d.ts +84 -26
package/dist/runtime/template-compiler/lru-cache.d.ts +0 -3
package/dist/runtime/types.d.ts +18 -0
package/dist/runtime/vdom-helpers.d.ts +0 -1
package/dist/runtime/vdom-ssr-dsd.d.ts +58 -0
package/dist/ssr-middleware.d.ts +125 -0
package/dist/ssr.d.ts +120 -16
package/dist/{transitions-DMJXs_tY.js → style-BmyOIMcU.js} +904 -1344
package/dist/style-BmyOIMcU.js.map +1 -0
package/dist/style-D40DsIqJ.cjs +55 -0
package/dist/style-D40DsIqJ.cjs.map +1 -0
package/dist/style.css +1 -1
package/dist/template-compiler-Cshhqxyd.cjs +23 -0
package/dist/template-compiler-Cshhqxyd.cjs.map +1 -0
package/dist/template-compiler-DtpNsqE-.js +3744 -0
package/dist/template-compiler-DtpNsqE-.js.map +1 -0
package/dist/variables.css +1 -1
package/dist/vite-plugin.d.ts +142 -0
package/package.json +60 -6
package/dist/namespace-helpers-Ctd_h7j2.cjs +0 -5
package/dist/namespace-helpers-Ctd_h7j2.cjs.map +0 -1
package/dist/namespace-helpers-DhLBqt-7.js +0 -1009
package/dist/namespace-helpers-DhLBqt-7.js.map +0 -1
package/dist/template-compiler-Bvx02nAT.js +0 -4020
package/dist/template-compiler-Bvx02nAT.js.map +0 -1
package/dist/template-compiler-bj-MFC_Y.cjs +0 -23
package/dist/template-compiler-bj-MFC_Y.cjs.map +0 -1
package/dist/transitions-DMJXs_tY.js.map +0 -1
package/dist/transitions-f4KfN29T.cjs +0 -330
package/dist/transitions-f4KfN29T.cjs.map +0 -1

package/dist/ssr-middleware.d.ts ADDED Viewed

@@ -0,0 +1,125 @@
+/**
+ * SSR middleware helpers for Express, Fastify, Hono, and other Node.js HTTP frameworks.
+ *
+ * Provides two handler factories that wrap the SSR rendering pipeline and
+ * emit a complete HTML document response. Both accept a static VNode **or**
+ * a per-request factory function so route-specific data can be threaded into
+ * the render tree.
+ *
+ * @example Express — static VNode
+ * ```ts
+ * import express from 'express';
+ * import { createSSRHandler } from '@jasonshimmy/custom-elements-runtime/ssr-middleware';
+ * import { html } from '@jasonshimmy/custom-elements-runtime';
+ *
+ * const app = express();
+ * app.get('/', createSSRHandler(html`<my-app />`, {
+ *   render: { dsd: true, jit: { extendedColors: true } },
+ * }));
+ * ```
+ *
+ * @example Express — per-request factory
+ * ```ts
+ * app.get('*', createSSRHandler(
+ *   (req) => html`<my-app url="${req.url}" />`,
+ *   { render: { dsd: true }, head: '<link rel="stylesheet" href="/app.css">' },
+ * ));
+ * ```
+ *
+ * @example Streaming variant
+ * ```ts
+ * app.get('*', createStreamingSSRHandler(
+ *   (req) => html`<my-app url="${req.url}" />`,
+ * ));
+ * ```
+ */
+import type { VNode } from './runtime/types';
+import type { RenderOptions } from './runtime/vdom-ssr';
+import type { DSDRenderOptions } from './runtime/vdom-ssr-dsd';
+import type { JITCSSOptions } from './runtime/style';
+/**
+ * Minimal request interface compatible with Express, Fastify, Hono, and the
+ * raw Node.js `IncomingMessage`. Extend or replace with your framework's
+ * request type via the generic parameter on `createSSRHandler`.
+ */
+export interface MinimalRequest {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string | string[] | undefined>;
+}
+/**
+ * Minimal response interface compatible with Express, Fastify, Hono, and the
+ * raw Node.js `ServerResponse`. `write` is optional — handlers fall back to
+ * buffering when it is absent.
+ */
+export interface MinimalResponse {
+    setHeader(name: string, value: string): void;
+    write?(chunk: string): boolean | void;
+    end(data?: string): void;
+}
+/**
+ * Options for {@link createSSRHandler} and {@link createStreamingSSRHandler}.
+ */
+export interface SSRMiddlewareOptions {
+    /**
+     * Render options forwarded to `renderToStringWithJITCSS`.
+     * Defaults to `{ dsd: true }` so DSD output is on by default.
+     */
+    render?: RenderOptions & DSDRenderOptions & {
+        jit?: JITCSSOptions;
+    };
+    /**
+     * Additional HTML inserted at the end of the `<head>` tag.
+     * Use this to inject `<link>`, `<script>`, `<meta>`, or `<title>` tags.
+     */
+    head?: string;
+    /**
+     * When `true` (default), the response is wrapped in a complete
+     * `<!DOCTYPE html>` document shell. Set to `false` if you want to
+     * assemble the document yourself and only need the rendered fragment.
+     */
+    document?: boolean;
+}
+/**
+ * Create a request handler that SSR-renders a VNode tree and sends the full
+ * HTML document as the response.
+ *
+ * Compatible with Express, Fastify, Hono, and any framework that uses an
+ * `(req, res)` handler signature. The generic `Req` parameter lets you use
+ * your framework's typed request object.
+ *
+ * @param vnodeOrFactory - A static {@link VNode} **or** a (possibly async)
+ *   factory function that receives the request and returns the VNode to render.
+ * @param options - Render and document-shell options.
+ *
+ * @example
+ * ```ts
+ * app.get('*', createSSRHandler(
+ *   (req) => html`<my-app url="${req.url}" />`,
+ *   { render: { dsd: true, jit: { extendedColors: true } } },
+ * ));
+ * ```
+ */
+export declare function createSSRHandler<Req extends MinimalRequest = MinimalRequest>(vnodeOrFactory: VNode | ((req: Req) => VNode | Promise<VNode>), options?: SSRMiddlewareOptions): (req: Req, res: MinimalResponse) => Promise<void>;
+/**
+ * Create a request handler that SSR-renders a VNode tree and streams the HTML
+ * response using chunked transfer encoding.
+ *
+ * Each chunk produced by the underlying {@link renderToStream} call is written
+ * to the response as it becomes available, minimising Time-to-First-Byte.
+ * The document shell preamble (`<!DOCTYPE html>…<body>`) is sent in the first
+ * write so the browser can begin parsing immediately.
+ *
+ * @param vnodeOrFactory - A static {@link VNode} **or** a (possibly async)
+ *   factory function that receives the request and returns the VNode to render.
+ * @param options - Render and document-shell options.
+ *
+ * @example
+ * ```ts
+ * app.get('*', createStreamingSSRHandler(
+ *   (req) => html`<my-app url="${req.url}" />`,
+ *   { render: { dsd: true } },
+ * ));
+ * ```
+ */
+export declare function createStreamingSSRHandler<Req extends MinimalRequest = MinimalRequest>(vnodeOrFactory: VNode | ((req: Req) => VNode | Promise<VNode>), options?: SSRMiddlewareOptions): (req: Req, res: MinimalResponse) => Promise<void>;

package/dist/ssr.d.ts CHANGED Viewed

@@ -1,28 +1,132 @@
 /**
- * SSR entrypoint — small re-export so consumers can import SSR-only helpers
- * without pulling them into the main client runtime bundle.
+ * SSR entry point — import from `@jasonshimmy/custom-elements-runtime/ssr`.
  *
- * renderToString accepts an optional second argument to control SSR behavior:
+ * Provides four rendering modes:
  *
- *   renderToString(vnode, { injectSvgNamespace?: boolean })
+ * 1. **renderToString** — baseline HTML serialisation (no shadow DOM content).
+ *    Backwards-compatible with the original API.
  *
- * - injectSvgNamespace (default: true): when true, the SSR renderer will
- *   inject the standard SVG namespace attribute (xmlns="http://www.w3.org/2000/svg")
- *   onto `<svg>` elements that do not already provide an explicit `xmlns`.
- *   This matches the client runtime behavior (createElementNS) and avoids
- *   hydration/namespace mismatches. Set to `false` to opt out and keep SSR
- *   output minimal.
+ * 2. **renderToStringWithJITCSS** — HTML + pre-generated JIT CSS injected into
+ *    `<head>` to prevent FOUC. Supports `dsd: true` for DSD output.
  *
- * Examples
+ * 3. **renderToStringWithJITCSSDSD** — convenience alias for DSD mode.
+ *    Full Declarative Shadow DOM output with per-shadow-root CSS layer stack
+ *    (baseReset + useStyle() + JIT CSS). Enables true hydration, zero FOUC.
  *
- *   // Default (injects xmlns for <svg> if missing)
- *   import { renderToString } from '@jasonshimmy/custom-elements-runtime/ssr';
- *   const html = renderToString(vnodeTree);
+ * 4. **renderToStream** — ReadableStream variant for streaming SSR.
  *
- *   // Opt-out
- *   const htmlNoNs = renderToString(vnodeTree, { injectSvgNamespace: false });
+ * Entity map utilities are also exported for full HTML5 named-entity support.
+ *
+ * @example DSD usage (recommended)
+ * ```ts
+ * import { renderToStringWithJITCSSDSD } from '@jasonshimmy/custom-elements-runtime/ssr';
+ *
+ * const { htmlWithStyles } = renderToStringWithJITCSSDSD(appVNode, {
+ *   jit: { extendedColors: true },
+ * });
+ * res.send(`<!DOCTYPE html><html><head>${head}</head><body>${htmlWithStyles}</body></html>`);
+ * ```
  */
 export { renderToString } from './runtime/vdom-ssr';
 export type { VNode } from './runtime/types';
 export type { RenderOptions } from './runtime/vdom-ssr';
 export { registerEntityMap, loadEntityMap, clearRegisteredEntityMap, } from './runtime/helpers';
+export { renderToStringDSD, DSD_POLYFILL_SCRIPT, } from './runtime/vdom-ssr-dsd';
+export type { DSDRenderOptions } from './runtime/vdom-ssr-dsd';
+import { type JITCSSOptions } from './runtime/style';
+import type { VNode } from './runtime/types';
+import type { RenderOptions } from './runtime/vdom-ssr';
+import type { DSDRenderOptions } from './runtime/vdom-ssr-dsd';
+/**
+ * Result of `renderToStringWithJITCSS()` and `renderToStringWithJITCSSDSD()`.
+ */
+export interface SSRJITResult {
+    /** The rendered HTML string (styles not yet injected). */
+    html: string;
+    /**
+     * Global JIT CSS extracted from the rendered HTML.
+     * For DSD renders, each shadow root embeds its own scoped styles; this field
+     * holds any residual light-DOM utility CSS.
+     */
+    css: string;
+    /**
+     * CSS captured from `useGlobalStyle()` calls during this render pass
+     * (e.g. `@font-face`, `:root` custom properties).
+     * Inject in a `<style id="cer-ssr-global">` in `<head>`.
+     */
+    globalStyles: string;
+    /**
+     * Convenience: `html` with both `<style>` tags injected before `</head>`.
+     * If no `</head>` is found, the styles are prepended.
+     */
+    htmlWithStyles: string;
+}
+/**
+ * Server-side render a VNode tree and simultaneously pre-generate JIT CSS.
+ *
+ * Pass `dsd: true` to enable Declarative Shadow DOM output with full per-shadow-
+ * root CSS layer extraction (recommended for new apps).
+ *
+ * @example Standard (no DSD)
+ * ```ts
+ * const { htmlWithStyles } = renderToStringWithJITCSS(appVNode);
+ * ```
+ *
+ * @example With DSD
+ * ```ts
+ * const { htmlWithStyles } = renderToStringWithJITCSS(appVNode, {
+ *   dsd: true,
+ *   jit: { extendedColors: true },
+ * });
+ * ```
+ */
+export declare function renderToStringWithJITCSS(vnode: VNode, options?: RenderOptions & DSDRenderOptions & {
+    jit?: JITCSSOptions;
+}): SSRJITResult;
+/**
+ * Convenience alias: `renderToStringWithJITCSS(vnode, { dsd: true, ...options })`.
+ *
+ * Renders with Declarative Shadow DOM output, full per-shadow-root CSS layer
+ * extraction, and the DSD browser polyfill. This is the recommended function
+ * for all new server-rendered applications.
+ *
+ * @example
+ * ```ts
+ * import { renderToStringWithJITCSSDSD } from '@jasonshimmy/custom-elements-runtime/ssr';
+ *
+ * const { htmlWithStyles } = renderToStringWithJITCSSDSD(appVNode, {
+ *   jit: { extendedColors: true },
+ * });
+ * ```
+ */
+export declare function renderToStringWithJITCSSDSD(vnode: VNode, options?: Omit<RenderOptions & DSDRenderOptions & {
+    jit?: JITCSSOptions;
+}, 'dsd'>): SSRJITResult;
+/**
+ * Render a VNode tree to a `ReadableStream<string>`.
+ *
+ * The current implementation flushes the complete rendered output as a single
+ * chunk, providing the streaming API surface for framework adapters. True
+ * incremental streaming (flush shell immediately, resolve async components
+ * progressively) is planned for a future release.
+ *
+ * @example Node.js
+ * ```ts
+ * import { renderToStream } from '@jasonshimmy/custom-elements-runtime/ssr';
+ *
+ * app.get('/', (req, res) => {
+ *   const stream = renderToStream(appVNode, { dsd: true });
+ *   const reader = stream.getReader();
+ *   const pump = () =>
+ *     reader.read().then(({ value, done }) => {
+ *       if (done) { res.end(); return; }
+ *       res.write(value);
+ *       pump();
+ *     });
+ *   pump();
+ * });
+ * ```
+ */
+export declare function renderToStream(vnode: VNode, options?: RenderOptions & DSDRenderOptions & {
+    jit?: JITCSSOptions;
+}): ReadableStream<string>;