feat(core): add public API for core

Author: mcous

package.json

@@ -8,6 +8,10 @@
       "types": "./types/index.d.ts",
       "default": "./src/index.js"
     },
+    "./core": {
+      "types": "./types/core/index.d.ts",
+      "default": "./src/core/index.js"
+    },
     "./svelte5": {
       "types": "./types/index.d.ts",
       "default": "./src/index.js"
@@ -53,7 +57,7 @@
     "!__tests__"
   ],
   "scripts": {
-    "toc": "doctoc README.md",
+    "toc": "doctoc README.md src/core/README.md",
     "lint": "prettier . --check && eslint .",
     "lint:delta": "npm-run-all -p prettier:delta eslint:delta",
     "prettier:delta": "prettier --check `./scripts/changed-files`",

src/core/README.md

@@ -0,0 +1,80 @@
+# @testing-library/svelte core
+
+Do you want to build your own Svelte testing library? You may want to use our rendering core, which abstracts away differences in Svelte versions to provide a simple API to render Svelte components into the document and clean them up afterwards
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [Usage](#usage)
+- [API](#api)
+  - [`prepareDocument`](#preparedocument)
+  - [`renderComponent`](#rendercomponent)
+  - [`cleanup`](#cleanup)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Usage
+
+```ts
+import { prepareDocument, renderComponent, cleanup } from '@testing-library/svelte/core'
+import MyCoolComponent from './my-cool-component.svelte'
+
+const { baseElement, target, options } = prepareDocument({ awesome: true })
+const { component, unmount, rerender } = renderComponent(MyCoolComponent, options)
+
+// later
+cleanup()
+```
+
+## API
+
+### `prepareDocument`
+
+Validate options and prepare document elements for rendering.
+
+```ts
+const { baseElement, target, options } = prepareDocument(propsOrOptions, renderOptions)
+```
+
+| Argument         | Type                                     | Description                                                           |
+| ---------------- | ---------------------------------------- | --------------------------------------------------------------------- |
+| `propsOrOptions` | `Props` or partial [component options][] | The component's props, or options to pass to Svelte's client-side API |
+| `renderOptions`  | `{ baseElement?: HTMLElement }`          | customize `baseElement`; will be `document.body` if unspecified       |
+
+| Result        | Type                  | Description                                                          |
+| ------------- | --------------------- | -------------------------------------------------------------------- |
+| `baseElement` | `HTMLElement`         | The base element, `document.body` by default                         |
+| `target`      | `HTMLElement`         | The component's `target` element, a `<div>` by default               |
+| `options`     | [component options][] | Validated and normalized Svelte options to pass to `renderComponent` |
+
+[component options]: https://svelte.dev/docs/client-side-component-api
+
+### `renderComponent`
+
+Render a Svelte component into the document.
+
+```ts
+const { component, unmount, rerender } = renderComponent(Component, options)
+```
+
+| Argument    | Type                  | Description                  |
+| ----------- | --------------------- | ---------------------------- |
+| `Component` | [Svelte component][]  | An imported Svelte component |
+| `options`   | [component options][] | Svelte component options     |
+
+| Result      | Type                                       | Description                                        |
+| ----------- | ------------------------------------------ | -------------------------------------------------- |
+| `component` | [component instance][]                     | The component instance                             |
+| `unmount`   | `() => void`                               | Unmount the component from the document            |
+| `rerender`  | `(props: Partial<Props>) => Promise<void>` | Update the component's props and wait for rerender |
+
+[Svelte component]: https://svelte.dev/docs/svelte-components
+[component instance]: https://svelte.dev/docs/client-side-component-api
+
+### `cleanup`
+
+Cleanup rendered components and added elements. Call this when your tests are over.
+
+```ts
+cleanup()
+```

src/core/cleanup.js

@@ -0,0 +1,30 @@
+/** @type {Map<unknown, () => void} */
+const itemsToClean = new Map()
+
+/** Register an item for later cleanup. */
+const addItemToCleanup = (item, onCleanup) => {
+  itemsToClean.set(item, onCleanup)
+}
+
+/** Remove an individual item from cleanup without running its cleanup handler. */
+const removeItemFromCleanup = (item) => {
+  itemsToClean.delete(item)
+}
+
+/** Clean up an individual item. */
+const cleanupItem = (item) => {
+  const handleCleanup = itemsToClean.get(item)
+  handleCleanup?.()
+  itemsToClean.delete(item)
+}
+
+/** Clean up all components and elements added to the document. */
+const cleanup = () => {
+  for (const handleCleanup of itemsToClean.values()) {
+    handleCleanup()
+  }
+
+  itemsToClean.clear()
+}
+
+export { addItemToCleanup, cleanup, cleanupItem, removeItemFromCleanup }

src/core/index.js

@@ -5,23 +5,6 @@
  * Will switch to legacy, class-based mounting logic
  * if it looks like we're in a Svelte <= 4 environment.
  */
-import * as LegacyCore from './legacy.js'
-import * as ModernCore from './modern.svelte.js'
-import {
-  createValidateOptions,
-  UnknownSvelteOptionsError,
-} from './validate-options.js'
-
-const { mount, unmount, updateProps, allowedOptions } =
-  ModernCore.IS_MODERN_SVELTE ? ModernCore : LegacyCore
-
-/** Validate component options. */
-const validateOptions = createValidateOptions(allowedOptions)
-
-export {
-  mount,
-  UnknownSvelteOptionsError,
-  unmount,
-  updateProps,
-  validateOptions,
-}
+export { cleanup } from './cleanup.js'
+export { mount, prepareDocument } from './mount.js'
+export { UnknownSvelteOptionsError } from './validate-options.js'

src/core/legacy.js

@@ -0,0 +1,43 @@
+/**
+ * Legacy rendering core for svelte-testing-library.
+ *
+ * Supports Svelte <= 4.
+ */
+
+import { removeItemFromCleanup } from './cleanup.js'
+
+/** Allowed options for the component constructor. */
+const allowedOptions = [
+  'target',
+  'accessors',
+  'anchor',
+  'props',
+  'hydrate',
+  'intro',
+  'context',
+]
+
+/** Mount the component into the DOM. */
+const mountComponent = (Component, options) => {
+  const component = new Component(options)
+
+  // This `$$.on_destroy` handler is included for strict backwards compatibility
+  // with previous versions of this library. It's mostly unnecessary logic.
+  component.$$.on_destroy.push(() => {
+    removeItemFromCleanup(component)
+  })
+
+  /** Remove the component from the DOM. */
+  const unmountComponent = () => {
+    component.$destroy()
+  }
+
+  /** Update the component's props. */
+  const updateProps = (nextProps) => {
+    component.$set(nextProps)
+  }
+
+  return { component, unmountComponent, updateProps }
+}
+
+export { allowedOptions, mountComponent }

src/core/modern.svelte.js

@@ -0,0 +1,39 @@
+/**
+ * Modern rendering core for svelte-testing-library.
+ *
+ * Supports Svelte >= 5.
+ */
+import * as Svelte from 'svelte'
+
+/** Whether we're using Svelte >= 5. */
+const IS_MODERN_SVELTE = typeof Svelte.mount === 'function'
+
+/** Allowed options to the `mount` call. */
+const allowedOptions = [
+  'target',
+  'anchor',
+  'props',
+  'events',
+  'context',
+  'intro',
+]
+
+/** Mount the component into the DOM. */
+const mountComponent = (Component, options) => {
+  const props = $state(options.props ?? {})
+  const component = Svelte.mount(Component, { ...options, props })
+
+  /** Remove the component from the DOM. */
+  const unmountComponent = () => {
+    Svelte.unmount(component)
+  }
+
+  /** Update the component's props. */
+  const updateProps = (nextProps) => {
+    Object.assign(props, nextProps)
+  }
+
+  return { component, unmountComponent, updateProps }
+}
+
+export { allowedOptions, IS_MODERN_SVELTE, mountComponent }