refactor(core): move all rendering and cleanup logic into core

Author: mcous

eslint.config.js

@@ -68,6 +68,7 @@ export default tseslint.config(
     name: 'extras',
     rules: {
       'unicorn/prevent-abbreviations': 'off',
+      'unicorn/prefer-dom-node-append': 'off',
     },
   },
   {

package.json

@@ -21,7 +21,7 @@
     "test:all": "pnpm test:vitest:jsdom && pnpm test:vitest:happy-dom && pnpm test:jest && pnpm test:examples",
     "test:all:legacy": "pnpm test:vitest:jsdom && pnpm test:vitest:happy-dom && pnpm test:jest",
     "build": "pnpm build:types && pnpm build:docs",
-    "build:types": "tsc --build && cp packages/svelte/src/component-types.d.ts packages/svelte/types",
+    "build:types": "tsc --build && cp packages/svelte/src/core/types.d.ts packages/svelte/types/core",
     "build:docs": "remark --output --use remark-toc --use remark-code-import --use unified-prettier README.md examples && cp -f README.md packages/svelte",
     "contributors:add": "all-contributors add",
     "contributors:generate": "all-contributors generate",

packages/svelte/src/core/index.js

@@ -5,9 +5,6 @@
  * Will switch to legacy, class-based mounting logic
  * if it looks like we're in a Svelte <= 4 environment.
  */
-export { addCleanupTask, cleanup } from './cleanup.js'
-export { mount } from './mount.js'
-export {
-  UnknownSvelteOptionsError,
-  validateOptions,
-} from './validate-options.js'
+export * from './cleanup.js'
+export * from './mount.js'
+export * from './setup.js'

packages/svelte/src/core/mount.js

@@ -5,14 +5,7 @@ import * as Svelte from 'svelte'
 
 import { addCleanupTask, removeCleanupTask } from './cleanup.js'
 import { createProps } from './props.svelte.js'
-
-/** Whether we're using Svelte >= 5. */
-const IS_MODERN_SVELTE = typeof Svelte.mount === 'function'
-
-/** Allowed options to the `mount` call or legacy component constructor. */
-const ALLOWED_MOUNT_OPTIONS = IS_MODERN_SVELTE
-  ? ['target', 'anchor', 'props', 'events', 'context', 'intro']
-  : ['target', 'accessors', 'anchor', 'props', 'hydrate', 'intro', 'context']
+import { IS_MODERN_SVELTE } from './svelte-version.js'
 
 /** Mount a modern Svelte 5 component into the DOM. */
 const mountModern = (Component, options) => {
@@ -92,4 +85,4 @@ const mount = (Component, options = {}) => {
   }
 }
 
-export { ALLOWED_MOUNT_OPTIONS, mount }
+export { mount }

packages/svelte/src/core/setup.js

@@ -0,0 +1,86 @@
+/** Set up the document to render a component. */
+import { addCleanupTask } from './cleanup.js'
+import { IS_MODERN_SVELTE } from './svelte-version.js'
+
+/** Allowed options to the `mount` call or legacy component constructor. */
+const ALLOWED_MOUNT_OPTIONS = IS_MODERN_SVELTE
+  ? ['target', 'anchor', 'props', 'events', 'context', 'intro']
+  : ['target', 'accessors', 'anchor', 'props', 'hydrate', 'intro', 'context']
+
+class UnknownSvelteOptionsError extends TypeError {
+  constructor(unknownOptions) {
+    super(`Unknown options.
+
+    Unknown: [ ${unknownOptions.join(', ')} ]
+    Allowed: [ ${ALLOWED_MOUNT_OPTIONS.join(', ')} ]
+
+    To pass both Svelte options and props to a component,
+    or to use props that share a name with a Svelte option,
+    you must place all your props under the \`props\` key:
+
+    render(Component, { props: { /** props here **/ } })
+`)
+    this.name = 'UnknownSvelteOptionsError'
+  }
+}
+
+/**
+ * Validate a component's mount options.
+ *
+ * @template {import('./types.js').Component} C
+ * @param {import('./types.js').ComponentOptions<C>} options - props or mount options
+ * @returns {Partial<import('./types.js').MountOptions<C>>}
+ */
+const validateOptions = (options) => {
+  const isProps = !Object.keys(options).some((option) =>
+    ALLOWED_MOUNT_OPTIONS.includes(option)
+  )
+
+  if (isProps) {
+    return { props: options }
+  }
+
+  // Check if any props and Svelte options were accidentally mixed.
+  const unknownOptions = Object.keys(options).filter(
+    (option) => !ALLOWED_MOUNT_OPTIONS.includes(option)
+  )
+
+  if (unknownOptions.length > 0) {
+    throw new UnknownSvelteOptionsError(unknownOptions, ALLOWED_MOUNT_OPTIONS)
+  }
+
+  return options
+}
+
+/**
+ * Set up the document to render a component.
+ *
+ * @template {import('./types.js').Component} C
+ * @param {import('./types.js').ComponentOptions<C>} options - props or mount options
+ * @param {{ baseElement?: HTMLElement | undefined }} setupOptions - base element of the document to bind any queries
+ * @returns {{
+ *   baseElement: HTMLElement,
+ *   target: HTMLElement,
+ *   mountOptions: import('./types.js).MountOptions<C>
+ * }}
+ */
+const setup = (options, setupOptions) => {
+  const mountOptions = validateOptions(options)
+  const baseElement =
+    setupOptions.baseElement ?? mountOptions.target ?? document.body
+  let target = mountOptions.target
+
+  if (!target) {
+    target = baseElement.appendChild(document.createElement('div'))
+  }
+
+  addCleanupTask(() => {
+    if (target.parentNode === document.body) {
+      target.remove()
+    }
+  })
+
+  return { baseElement, target, mountOptions: { ...mountOptions, target } }
+}
+
+export { setup, UnknownSvelteOptionsError }

packages/svelte/src/core/svelte-version.js

@@ -0,0 +1,7 @@
+/** Detect which version of Svelte we're using */
+import * as Svelte from 'svelte'
+
+/** Whether we're using Svelte >= 5. */
+const IS_MODERN_SVELTE = typeof Svelte.mount === 'function'
+
+export { IS_MODERN_SVELTE }

packages/svelte/src/component-types.d.ts renamed to packages/svelte/src/core/types.d.ts

@@ -1,4 +1,9 @@
 /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-deprecated */
+/**
+ * Component and utility types.
+ *
+ * Supports components from Svelte 3, 4, and 5.
+ */
 import type {
   Component as ModernComponent,
   ComponentConstructorOptions as LegacyConstructorOptions,
@@ -59,3 +64,8 @@ export type Exports<C> = IS_MODERN_SVELTE extends true
 export type MountOptions<C extends Component> = IS_MODERN_SVELTE extends true
   ? Parameters<typeof mount<Props<C>, Exports<C>>>[1]
   : LegacyConstructorOptions<Props<C>>
+
+/** A component's props or some of its mount options. */
+export type ComponentOptions<C extends Component> =
+  | Props<C>
+  | Partial<MountOptions<C>>

packages/svelte/src/core/validate-options.js

@@ -23,7 +23,6 @@ if (typeof process !== 'undefined' && !process.env.STL_SKIP_AUTO_CLEANUP) {
 export * from '@testing-library/dom'
 
 // export svelte-specific functions and custom `fireEvent`
-export { UnknownSvelteOptionsError } from './core/index.js'
 export * from './pure.js'
 // `fireEvent` must be named to take priority over wildcard from @testing-library/dom
 export { fireEvent } from './pure.js'

packages/svelte/src/index.js

@@ -7,13 +7,13 @@ import {
 } from '@testing-library/dom'
 import * as Svelte from 'svelte'
 
-import { addCleanupTask, mount, validateOptions } from './core/index.js'
+import { addCleanupTask, mount, setup as coreSetup } from './core/index.js'
 
 /**
  * Customize how Svelte renders the component.
  *
- * @template {import('./component-types.js').Component} C
- * @typedef {import('./component-types.js').Props<C> | Partial<import('./component-types.js').MountOptions<C>>} SvelteComponentOptions
+ * @template {import('./core/types.js').Component} C
+ * @typedef {import('./core/types.js').ComponentOptions<C>} SvelteComponentOptions
  */
 
 /**
@@ -29,15 +29,15 @@ import { addCleanupTask, mount, validateOptions } from './core/index.js'
 /**
  * The rendered component and bound testing functions.
  *
- * @template {import('./component-types.js').Component} C
+ * @template {import('./core/types.js').Component} C
  * @template {import('@testing-library/dom').Queries} [Q=typeof import('@testing-library/dom').queries]
  *
  * @typedef {{
  *   container: HTMLElement
  *   baseElement: HTMLElement
- *   component: import('./component-types.js').Exports<C>
+ *   component: import('./core/types.js').Exports<C>
  *   debug: (el?: HTMLElement | DocumentFragment) => void
- *   rerender: (props: Partial<import('./component-types.js').Props<C>>) => Promise<void>
+ *   rerender: (props: Partial<import('./core/types.js').Props<C>>) => Promise<void>
  *   unmount: () => void
  * } & {
  *   [P in keyof Q]: import('@testing-library/dom').BoundFunction<Q[P]>
@@ -47,35 +47,25 @@ import { addCleanupTask, mount, validateOptions } from './core/index.js'
 /**
  * Render a component into the document.
  *
- * @template {import('./component-types.js').Component} C
+ * @template {import('./core/types.js').Component} C
  * @template {import('@testing-library/dom').Queries} [Q=typeof import('@testing-library/dom').queries]
  *
- * @param {import('./component-types.js').ComponentType<C>} Component - The component to render.
+ * @param {import('./core/types.js').ComponentType<C>} Component - The component to render.
  * @param {SvelteComponentOptions<C>} options - Customize how Svelte renders the component.
  * @param {RenderOptions<Q>} renderOptions - Customize how Testing Library sets up the document and binds queries.
  * @returns {RenderResult<C, Q>} The rendered component and bound testing functions.
  */
 const render = (Component, options = {}, renderOptions = {}) => {
-  options = validateOptions(options)
-
-  const baseElement =
-    renderOptions.baseElement ?? options.target ?? document.body
+  const { baseElement, target, mountOptions } = coreSetup(
+    options,
+    renderOptions
+  )
 
   const queries = getQueriesForElement(baseElement, renderOptions.queries)
 
-  const target =
-    // eslint-disable-next-line unicorn/prefer-dom-node-append
-    options.target ?? baseElement.appendChild(document.createElement('div'))
-
-  addCleanupTask(() => {
-    if (target.parentNode === document.body) {
-      target.remove()
-    }
-  })
-
   const { component, unmount, rerender } = mount(
     Component.default ?? Component,
-    { ...options, target }
+    mountOptions
   )
 
   return {
@@ -160,5 +150,5 @@ for (const [key, baseEvent] of Object.entries(baseFireEvent)) {
   fireEvent[key] = async (...args) => act(() => baseEvent(...args))
 }
 
-export { cleanup } from './core/index.js'
+export { cleanup, UnknownSvelteOptionsError } from './core/index.js'
 export { act, fireEvent, render, setup }