chore: move internals out of JSXNode

.changeset/good-jars-mix.md

@@ -0,0 +1,20 @@
+---
+'@builder.io/qwik': minor
+---
+
+CHORE: Prepare backwards compatibility for V1 libraries in V2.
+
+We move internal fields `immutableProps` and `flags` out of JSXNode as they are not meant for public use.
+
+This will allow projects using older V1 libraries to continue to work with the Qwik V2 by adding the following `package.json` changes:
+
+```json
+{
+  "dependencies": {
+    "@builder.io/qwik": "^1.11.0",
+    "@qwik.dev/core": "^2.0.0"
+  }
+}
+```
+
+And will prevent typescript errors when using libraries which haven't upgraded to V2 yet.

packages/docs/src/routes/api/qwik/api.json

@@ -1256,7 +1256,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "A JSX Node, an internal structure. You probably want to use `JSXOutput` instead.\n\n\n```typescript\nexport interface JSXNode<T extends string | FunctionComponent | unknown = unknown> \n```\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[children](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[JSXChildren](#jsxchildren) \\| null\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[dev?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[DevJSX](#devjsx)\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[flags](#)\n\n\n</td><td>\n\n\n</td><td>\n\nnumber\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[immutableProps](#)\n\n\n</td><td>\n\n\n</td><td>\n\nRecord&lt;any, unknown&gt; \\| null\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[key](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring \\| null\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[props](#)\n\n\n</td><td>\n\n\n</td><td>\n\nT extends [FunctionComponent](#functioncomponent)<!-- -->&lt;infer P&gt; ? P : Record&lt;any, unknown&gt;\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[type](#)\n\n\n</td><td>\n\n\n</td><td>\n\nT\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
+      "content": "A JSX Node, an internal structure. You probably want to use `JSXOutput` instead.\n\n\n```typescript\nexport interface JSXNode<T extends string | FunctionComponent | unknown = unknown> \n```\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\n[children](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[JSXChildren](#jsxchildren) \\| null\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[dev?](#)\n\n\n</td><td>\n\n\n</td><td>\n\n[DevJSX](#devjsx)\n\n\n</td><td>\n\n_(Optional)_\n\n\n</td></tr>\n<tr><td>\n\n[key](#)\n\n\n</td><td>\n\n\n</td><td>\n\nstring \\| null\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[props](#)\n\n\n</td><td>\n\n\n</td><td>\n\nT extends [FunctionComponent](#functioncomponent)<!-- -->&lt;infer P&gt; ? P : Record&lt;any, unknown&gt;\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\n[type](#)\n\n\n</td><td>\n\n\n</td><td>\n\nT\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/render/jsx/types/jsx-node.ts",
       "mdFile": "qwik.jsxnode.md"
     },
@@ -1760,7 +1760,7 @@
         }
       ],
       "kind": "Function",
-      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nLoad the prefetch graph for the container.\n\nEach Qwik container needs to include its own prefetch graph.\n\n\n```typescript\nPrefetchGraph: (opts?: {\n    base?: string;\n    manifestHash?: string;\n    manifestURL?: string;\n    nonce?: string;\n}) => JSXNode<\"script\">\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nopts\n\n\n</td><td>\n\n{ base?: string; manifestHash?: string; manifestURL?: string; nonce?: string; }\n\n\n</td><td>\n\n_(Optional)_ Options for the loading prefetch graph.\n\n- `base` - Base of the graph. For a default installation this will default to the q:base value `/build/`<!-- -->. But if more than one MFE is installed on the page, then each MFE needs to have its own base. - `manifestHash` - Hash of the manifest file to load. If not provided the hash will be extracted from the container attribute `q:manifest-hash` and assume the default build file `${base}/q-bundle-graph-${manifestHash}.json`<!-- -->. - `manifestURL` - URL of the manifest file to load if non-standard bundle graph location name.\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\nJSXNode&lt;\"script\"&gt;",
+      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nLoad the prefetch graph for the container.\n\nEach Qwik container needs to include its own prefetch graph.\n\n\n```typescript\nPrefetchGraph: (opts?: {\n    base?: string;\n    manifestHash?: string;\n    manifestURL?: string;\n    nonce?: string;\n}) => JSXOutput\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nopts\n\n\n</td><td>\n\n{ base?: string; manifestHash?: string; manifestURL?: string; nonce?: string; }\n\n\n</td><td>\n\n_(Optional)_ Options for the loading prefetch graph.\n\n- `base` - Base of the graph. For a default installation this will default to the q:base value `/build/`<!-- -->. But if more than one MFE is installed on the page, then each MFE needs to have its own base. - `manifestHash` - Hash of the manifest file to load. If not provided the hash will be extracted from the container attribute `q:manifest-hash` and assume the default build file `${base}/q-bundle-graph-${manifestHash}.json`<!-- -->. - `manifestURL` - URL of the manifest file to load if non-standard bundle graph location name.\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\n[JSXOutput](#jsxoutput)",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/components/prefetch.ts",
       "mdFile": "qwik.prefetchgraph.md"
     },
@@ -1774,7 +1774,7 @@
         }
       ],
       "kind": "Function",
-      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nInstall a service worker which will prefetch the bundles.\n\nThere can only be one service worker per page. Because there can be many separate Qwik Containers on the page each container needs to load its prefetch graph using `PrefetchGraph` component.\n\n\n```typescript\nPrefetchServiceWorker: (opts: {\n    base?: string;\n    scope?: string;\n    path?: string;\n    verbose?: boolean;\n    fetchBundleGraph?: boolean;\n    nonce?: string;\n}) => JSXNode<'script'>\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nopts\n\n\n</td><td>\n\n{ base?: string; scope?: string; path?: string; verbose?: boolean; fetchBundleGraph?: boolean; nonce?: string; }\n\n\n</td><td>\n\nOptions for the prefetch service worker.\n\n- `base` - Base URL for the service worker `import.meta.env.BASE_URL` or `/`<!-- -->. Default is `import.meta.env.BASE_URL` - `scope` - Base URL for when the service-worker will activate. Default is `/` - `path` - Path to the service worker. Default is `qwik-prefetch-service-worker.js` unless you pass a path that starts with a `/` then the base is ignored. Default is `qwik-prefetch-service-worker.js` - `verbose` - Verbose logging for the service worker installation. Default is `false` - `nonce` - Optional nonce value for security purposes, defaults to `undefined`<!-- -->.\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\nJSXNode&lt;'script'&gt;",
+      "content": "> This API is provided as an alpha preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.\n> \n\nInstall a service worker which will prefetch the bundles.\n\nThere can only be one service worker per page. Because there can be many separate Qwik Containers on the page each container needs to load its prefetch graph using `PrefetchGraph` component.\n\n\n```typescript\nPrefetchServiceWorker: (opts: {\n    base?: string;\n    scope?: string;\n    path?: string;\n    verbose?: boolean;\n    fetchBundleGraph?: boolean;\n    nonce?: string;\n}) => JSXNode<'script'>\n```\n\n\n<table><thead><tr><th>\n\nParameter\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nopts\n\n\n</td><td>\n\n{ base?: string; scope?: string; path?: string; verbose?: boolean; fetchBundleGraph?: boolean; nonce?: string; }\n\n\n</td><td>\n\nOptions for the prefetch service worker.\n\n- `base` - Base URL for the service worker `import.meta.env.BASE_URL` or `/`<!-- -->. Default is `import.meta.env.BASE_URL` - `scope` - Base URL for when the service-worker will activate. Default is `/` - `path` - Path to the service worker. Default is `qwik-prefetch-service-worker.js` unless you pass a path that starts with a `/` then the base is ignored. Default is `qwik-prefetch-service-worker.js` - `verbose` - Verbose logging for the service worker installation. Default is `false` - `nonce` - Optional nonce value for security purposes, defaults to `undefined`<!-- -->.\n\n\n</td></tr>\n</tbody></table>\n**Returns:**\n\n[JSXNode](#jsxnode)<!-- -->&lt;'script'&gt;",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/components/prefetch.ts",
       "mdFile": "qwik.prefetchserviceworker.md"
     },

packages/docs/src/routes/api/qwik/index.md

@@ -3043,32 +3043,6 @@ _(Optional)_
 </td></tr>
 <tr><td>
 
-[flags](#)
-
-</td><td>
-
-</td><td>
-
-number
-
-</td><td>
-
-</td></tr>
-<tr><td>
-
-[immutableProps](#)
-
-</td><td>
-
-</td><td>
-
-Record&lt;any, unknown&gt; \| null
-
-</td><td>
-
-</td></tr>
-<tr><td>
-
 [key](#)
 
 </td><td>
@@ -3591,7 +3565,7 @@ PrefetchGraph: (opts?: {
   manifestHash?: string;
   manifestURL?: string;
   nonce?: string;
-}) => JSXNode<"script">;
+}) => JSXOutput;
 ```
 
 <table><thead><tr><th>
@@ -3625,7 +3599,7 @@ _(Optional)_ Options for the loading prefetch graph.
 </tbody></table>
 **Returns:**
 
-JSXNode&lt;"script"&gt;
+[JSXOutput](#jsxoutput)
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/components/prefetch.ts)
 
@@ -3679,7 +3653,7 @@ Options for the prefetch service worker.
 </tbody></table>
 **Returns:**
 
-JSXNode&lt;'script'&gt;
+[JSXNode](#jsxnode)&lt;'script'&gt;
 
 [Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik/src/core/components/prefetch.ts)
 

packages/qwik/src/core/api.md

@@ -413,9 +413,10 @@ export { jsx as jsxs }
 export const _jsxBranch: <T>(input?: T) => T | undefined;
 
 // Warning: (ae-forgotten-export) The symbol "JsxDevOpts" needs to be exported by the entry point index.d.ts
+// Warning: (ae-forgotten-export) The symbol "JSXNodeInternal" needs to be exported by the entry point index.d.ts
 //
 // @internal
-export const _jsxC: <T extends string | FunctionComponent<Record<any, unknown>>>(type: T, mutableProps: (T extends FunctionComponent<infer PROPS> ? PROPS : Record<any, unknown>) | null, flags: number, key: string | number | null, dev?: JsxDevOpts) => JSXNode<T>;
+export const _jsxC: <T extends string | FunctionComponent<Record<any, unknown>>>(type: T, mutableProps: (T extends FunctionComponent<infer PROPS> ? PROPS : Record<any, unknown>) | null, flags: number, key: string | number | null, dev?: JsxDevOpts) => JSXNodeInternal<T>;
 
 // @public (undocumented)
 export type JSXChildren = string | number | boolean | null | undefined | Function | RegExp | JSXChildren[] | Promise<JSXChildren> | Signal<JSXChildren> | JSXNode;
@@ -430,10 +431,6 @@ export interface JSXNode<T extends string | FunctionComponent | unknown = unknow
     // (undocumented)
     dev?: DevJSX;
     // (undocumented)
-    flags: number;
-    // (undocumented)
-    immutableProps: Record<any, unknown> | null;
-    // (undocumented)
     key: string | null;
     // (undocumented)
     props: T extends FunctionComponent<infer P> ? P : Record<any, unknown>;
@@ -445,10 +442,10 @@ export interface JSXNode<T extends string | FunctionComponent | unknown = unknow
 export type JSXOutput = JSXNode | string | number | boolean | null | undefined | JSXOutput[];
 
 // @internal
-export const _jsxQ: <T extends string>(type: T, mutableProps: Record<any, unknown> | null, immutableProps: Record<any, unknown> | null, children: JSXChildren | null, flags: number, key: string | number | null, dev?: DevJSX) => JSXNode<T>;
+export const _jsxQ: <T extends string>(type: T, mutableProps: Record<any, unknown> | null, immutableProps: Record<any, unknown> | null, children: JSXChildren | null, flags: number, key: string | number | null, dev?: DevJSX) => JSXNodeInternal<T>;
 
 // @internal
-export const _jsxS: <T extends string>(type: T, mutableProps: Record<any, unknown> | null, immutableProps: Record<any, unknown> | null, flags: number, key: string | number | null, dev?: DevJSX) => JSXNode<T>;
+export const _jsxS: <T extends string>(type: T, mutableProps: Record<any, unknown> | null, immutableProps: Record<any, unknown> | null, flags: number, key: string | number | null, dev?: DevJSX) => JSXNodeInternal<T>;
 
 // @public (undocumented)
 export type JSXTagName = keyof HTMLElementTagNameMap | Omit<string, keyof HTMLElementTagNameMap>;
@@ -606,7 +603,7 @@ export const PrefetchGraph: (opts?: {
     manifestHash?: string;
     manifestURL?: string;
     nonce?: string;
-}) => JSXNode_2<"script">;
+}) => JSXOutput;
 
 // @alpha
 export const PrefetchServiceWorker: (opts: {

packages/qwik/src/core/components/prefetch.ts

@@ -2,6 +2,7 @@ import { isDev } from '@builder.io/qwik/build';
 import { _jsxC } from '../internal';
 import type { JSXNode } from '@builder.io/qwik/jsx-runtime';
 import { useServerData } from '../use/use-env-data';
+import type { JSXOutput } from '../render/jsx/types/jsx-node';
 
 /**
  * Install a service worker which will prefetch the bundles.
@@ -124,7 +125,7 @@ const PREFETCH_CODE = /*#__PURE__*/ ((
  */
 export const PrefetchGraph = (
   opts: { base?: string; manifestHash?: string; manifestURL?: string; nonce?: string } = {}
-) => {
+): JSXOutput => {
   const isTest = import.meta.env.TEST;
   if (isDev && !isTest) {
     const props = {

packages/qwik/src/core/container/serializers.ts

@@ -37,8 +37,8 @@ import { serializeDerivedSignalFunc } from '../qrl/inlined-fn';
 import type { QwikElement } from '../render/dom/virtual-element';
 import { assertString, assertTrue } from '../error/assert';
 import { Fragment, JSXNodeImpl, isJSXNode } from '../render/jsx/jsx-runtime';
-import type { JSXNode } from '@builder.io/qwik/jsx-runtime';
 import { Slot } from '../render/jsx/slot.public';
+import type { JSXNodeInternal } from '../render/jsx/types/jsx-node';
 
 /**
  * - 0, 8, 9, A, B, C, D
@@ -383,7 +383,7 @@ const FormDataSerializer = /*#__PURE__*/ serializer<FormData>({
   },
 });
 
-const JSXNodeSerializer = /*#__PURE__*/ serializer<JSXNode>({
+const JSXNodeSerializer = /*#__PURE__*/ serializer<JSXNodeInternal>({
   $prefix$: '\u0017',
   $test$: (v) => isJSXNode(v),
   $collect$: (node, collector, leaks) => {

packages/qwik/src/core/render/dom/render-dom.ts

@@ -8,7 +8,7 @@ import { isArray, isFunction, isObject, isString, type ValueOrPromise } from '..
 import { domToVnode, smartUpdateChildren } from './visitor';
 import { SkipRender } from '../jsx/utils.public';
 import { isJSXNode, SKIP_RENDER_TYPE, _jsxC, Virtual } from '../jsx/jsx-runtime';
-import type { DevJSX, JSXNode } from '../jsx/types/jsx-node';
+import type { DevJSX, JSXNodeInternal } from '../jsx/types/jsx-node';
 import { executeComponent, shouldWrapFunctional } from '../execute-component';
 import type { RenderContext } from '../types';
 import { type QwikElement, VIRTUAL, type VirtualElement } from './virtual-element';
@@ -88,7 +88,7 @@ export class ProcessedJSXNodeImpl implements ProcessedJSXNode {
 }
 
 export const processNode = (
-  node: JSXNode,
+  node: JSXNodeInternal,
   invocationContext?: InvokeContext
 ): ValueOrPromise<ProcessedJSXNode | ProcessedJSXNode[] | undefined> => {
   const { key, type, props, children, flags, immutableProps } = node;

packages/qwik/src/core/render/jsx/factory.unit.ts

@@ -1,6 +1,6 @@
 import { h } from './factory';
 import { isJSXNode, Fragment } from './jsx-runtime';
-import type { FunctionComponent } from './types/jsx-node';
+import type { FunctionComponent, JSXNodeInternal } from './types/jsx-node';
 import { type ProcessedJSXNode, processNode } from '../dom/render-dom';
 import { test, assert } from 'vitest';
 
@@ -19,7 +19,7 @@ test('map multiple nodes, flatten', () => {
       'a',
       [1, 2].map((n) => h('child', null, n)),
       'b'
-    )
+    ) as JSXNodeInternal
   ) as ProcessedJSXNode;
   assert.deepEqual(v.$children$.length, 4);
   assert.deepEqual(v.$children$[0].$text$, 'a');
@@ -32,7 +32,7 @@ test('map multiple nodes, flatten', () => {
 
 test('one child node', () => {
   // <parent><child></child></parent>
-  const v = processNode(h('parent', null, h('child', null))) as ProcessedJSXNode;
+  const v = processNode(h('parent', null, h('child', null)) as JSXNodeInternal) as ProcessedJSXNode;
   assert.deepEqual(v.$children$.length, 1);
   assert.deepEqual(v.$children$[0].$type$, 'child');
   assert.deepEqual(v.$children$[0].$props$, {});
@@ -41,7 +41,7 @@ test('one child node', () => {
 
 test('text w/ expression', () => {
   // <div>1 {2} 3</div>
-  const v = processNode(h('div', null, '1 ', 2, ' 3')) as ProcessedJSXNode;
+  const v = processNode(h('div', null, '1 ', 2, ' 3') as JSXNodeInternal) as ProcessedJSXNode;
   assert.deepEqual(v.$children$[0].$type$, '#text');
   assert.deepEqual(v.$children$[0].$text$, '1 ');
   assert.deepEqual(v.$children$[0].$key$, null);
@@ -57,15 +57,15 @@ test('text w/ expression', () => {
 
 test('text child', () => {
   // <div>text</div>
-  const v = processNode(h('div', null, 'text')) as ProcessedJSXNode;
+  const v = processNode(h('div', null, 'text') as JSXNodeInternal) as ProcessedJSXNode;
   assert.deepEqual(v.$children$[0].$type$, '#text');
   assert.deepEqual(v.$children$[0].$text$, 'text');
   assert.deepEqual(v.$children$[0].$key$, null);
 });
 
 test('no children', () => {
   // <div/>
-  const v = processNode(h('div', null)) as ProcessedJSXNode;
+  const v = processNode(h('div', null) as JSXNodeInternal) as ProcessedJSXNode;
   assert.deepEqual(v.$children$, []);
 });
 

packages/qwik/src/core/render/jsx/jsx-runtime.ts

@@ -1,4 +1,4 @@
-import type { DevJSX, FunctionComponent, JSXNode } from './types/jsx-node';
+import type { DevJSX, FunctionComponent, JSXNode, JSXNodeInternal } from './types/jsx-node';
 import type { QwikJSX } from './types/jsx-qwik';
 import { qDev, qRuntimeQrl, seal } from '../../util/qdev';
 import { logError, logOnceWarn, logWarn } from '../../util/log';
@@ -33,7 +33,7 @@ export const _jsxQ = <T extends string>(
   flags: number,
   key: string | number | null,
   dev?: DevJSX
-): JSXNode<T> => {
+): JSXNodeInternal<T> => {
   assertString(type, 'jsx type must be a string');
   const processed = key == null ? null : String(key);
   const node = new JSXNodeImpl<T>(
@@ -67,7 +67,7 @@ export const _jsxS = <T extends string>(
   flags: number,
   key: string | number | null,
   dev?: DevJSX
-): JSXNode<T> => {
+): JSXNodeInternal<T> => {
   let children: JSXChildren = null;
   if (mutableProps && 'children' in mutableProps) {
     children = mutableProps.children as JSXChildren;
@@ -87,7 +87,7 @@ export const _jsxC = <T extends string | FunctionComponent<Record<any, unknown>>
   flags: number,
   key: string | number | null,
   dev?: JsxDevOpts
-): JSXNode<T> => {
+): JSXNodeInternal<T> => {
   const processed = key == null ? null : String(key);
   const props = mutableProps ?? ({} as NonNullable<typeof mutableProps>);
   // In dynamic components, type could be a string
@@ -195,7 +195,7 @@ export const RenderOnce: FunctionComponent<{
   return new JSXNodeImpl(Virtual, EMPTY_OBJ, null, props.children, static_subtree, key);
 };
 
-const validateJSXNode = (node: JSXNode) => {
+const validateJSXNode = (node: JSXNodeInternal) => {
   if (qDev) {
     const { type, props, immutableProps, children } = node;
     invoke(undefined, () => {
@@ -320,7 +320,7 @@ const printObjectLiteral = (obj: Record<string, unknown>) => {
     .join(', ')} }`;
 };
 
-export const isJSXNode = (n: unknown): n is JSXNode => {
+export const isJSXNode = (n: unknown): n is JSXNodeInternal => {
   if (qDev) {
     if (n instanceof JSXNodeImpl) {
       return true;