feat(core): create standalone core module

Author: mcous

.editorconfig

@@ -8,5 +8,4 @@ insert_final_newline = true
 trim_trailing_whitespace = true
 
 [*.md]
-max_line_length = off
 trim_trailing_whitespace = false

package.json

@@ -20,8 +20,8 @@
     "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/core/types.d.ts packages/svelte/dist/core",
-    "build:docs": "remark --output --use remark-toc --use remark-code-import --use unified-prettier README.md examples && cp -f README.md packages/svelte",
+    "build:types": "tsc --build",
+    "build:docs": "remark --output --use remark-toc --use remark-code-import --use unified-prettier README.md packages/*/README.md examples && cp -f README.md packages/svelte",
     "contributors:add": "all-contributors add",
     "contributors:generate": "all-contributors generate",
     "install:3": "./scripts/install-dependencies 3",

packages/svelte-core/README.md

@@ -0,0 +1,147 @@
+# @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
+
+## Table of Contents
+
+- [Example Usage](#example-usage)
+- [API](#api)
+  - [`setup`](#setup)
+  - [`mount`](#mount)
+  - [`cleanup`](#cleanup)
+  - [`addCleanupTask`](#addcleanuptask)
+  - [`removeCleanupTask`](#removecleanuptask)
+  - [Utility types](#utility-types)
+
+## Example Usage
+
+```ts
+import { beforeEach } from 'vitest'
+import { cleanup, mount, setup } from '@testing-library/svelte-core'
+import type {
+  Component,
+  ComponentType,
+  ComponentOptions,
+  Props,
+  Exports,
+} from '@testing-library/svelte-core/types'
+
+import { bindQueries, type Screen } from './bring-your-own-queries.js'
+
+beforeEach(() => {
+  cleanup()
+})
+
+export interface RenderResult<C extends Component> {
+  screen: Screen
+  component: Exports<C>
+  target: HTMLElement
+  rerender: (props: Partial<Props<C>>) => Promise<void>
+  unmount: () => void
+}
+
+export const render = <C extends Component>(
+  component: ComponentType<C>,
+  options: ComponentOptions<C>
+): RenderResult<C> => {
+  const { baseElement, target, mountOptions } = setup(options)
+  const { component, unmount, rerender } = mount(component, mountOptions)
+  const screen = bindQueries(baseElement)
+
+  return { screen, component, target, rerender, unmount }
+}
+```
+
+## API
+
+### `setup`
+
+Validate options and prepare document elements for rendering.
+
+```ts
+const { baseElement, target, mountOptions } = setup(options, renderOptions)
+```
+
+| Argument           | Type                                     | Description                                    |
+| ------------------ | ---------------------------------------- | ---------------------------------------------- |
+| `componentOptions` | `Props` or partial [component options][] | Options for how the component will be rendered |
+| `setupOptions`     | `{ baseElement?: HTMLElement }`          | Optionally override `baseElement`              |
+
+| Result         | Type                  | Description                                 | Default                             |
+| -------------- | --------------------- | ------------------------------------------- | ----------------------------------- |
+| `baseElement`  | `HTMLElement`         | The base element                            | `document.body`                     |
+| `target`       | `HTMLElement`         | The component's `target` element            | `<div>` appended to `document.body` |
+| `mountOptions` | [component options][] | Validated Svelte options to pass to `mount` | `{ target, props: {} }`             |
+
+[component options]: https://svelte.dev/docs/client-side-component-api
+
+### `mount`
+
+Mount a Svelte component into the document.
+
+```ts
+const { component, unmount, rerender } = mount(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()
+```
+
+### `addCleanupTask`
+
+Add a custom cleanup task to be called with `cleanup()`
+
+```ts
+addCleanupTask(() => {
+  // ...reset something
+})
+```
+
+### `removeCleanupTask`
+
+Remove a cleanup task from `cleanup()`. Useful if a cleanup task can only be run
+once and may be run outside of `cleanup`
+
+```ts
+const customCleanup = () => {
+  // ...reset something
+}
+
+addCleanupTask(customCleanup)
+
+const manuallyCleanupEarly = () => {
+  customCleanup()
+  removeCleanupTask(customCleanup)
+}
+```
+
+### Utility types
+
+This module exports various utility types from
+`@testing-library/svelte-core/types`. They adapt to whatever Svelte version is
+installed, and can be used to get type signatures for imported components,
+props, events, etc.
+
+See [`./types.d.ts`](./types.d.ts) for the full list of types available.

packages/svelte-core/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@testing-library/svelte-core",
+  "version": "0.0.0-semantically-released",
+  "description": "Core rendering and cleanup logic for Svelte testing utilities.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./types": {
+      "types": "./types.d.ts"
+    }
+  },
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/testing-library/svelte-testing-library#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/testing-library/svelte-testing-library.git",
+    "directory": "packages/svelte-core"
+  },
+  "bugs": {
+    "url": "https://github.com/testing-library/svelte-testing-library/issues"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "testing",
+    "svelte",
+    "ui",
+    "dom",
+    "jsdom",
+    "unit",
+    "integration",
+    "functional",
+    "end-to-end",
+    "e2e"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "types.d.ts"
+  ],
+  "peerDependencies": {
+    "svelte": "^3 || ^4 || ^5 || ^5.0.0-next.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

packages/svelte/src/core/cleanup.js renamed to packages/svelte-core/src/cleanup.js

@@ -7,7 +7,18 @@ import { addCleanupTask, removeCleanupTask } from './cleanup.js'
 import { createProps } from './props.svelte.js'
 import { IS_MODERN_SVELTE } from './svelte-version.js'
 
-/** Mount a modern Svelte 5 component into the DOM. */
+/**
+ * Mount a modern Svelte 5 component into the DOM.
+ *
+ * @template {import('../types.js').Component} C
+ * @param {import('../types.js').ComponentType<C>} Component
+ * @param {import('../types.js').MountOptions<C>} options
+ * @returns {{
+ *   component: C
+ *   unmount: () => void
+ *   rerender: (props: Partial<import('../types.js').Props<C>>) => Promise<void>
+ * }}
+ */
 const mountModern = (Component, options) => {
   const [props, updateProps] = createProps(options.props)
   const component = Svelte.mount(Component, { ...options, props })
@@ -29,7 +40,18 @@ const mountModern = (Component, options) => {
   return { component, unmount, rerender }
 }
 
-/** Mount a legacy Svelte 3 or 4 component into the DOM. */
+/**
+ * Mount a legacy Svelte 3 or 4 component into the DOM.
+ *
+ * @template {import('../types.js').LegacyComponent} C
+ * @param {import('../types.js').ComponentType<C>} Component
+ * @param {import('../types.js').MountOptions<C>} options
+ * @returns {{
+ *   component: C
+ *   unmount: () => void
+ *   rerender: (props: Partial<import('../types.js').Props<C>>) => Promise<void>
+ * }}
+ */
 const mountLegacy = (Component, options) => {
   const component = new Component(options)
 
@@ -62,22 +84,32 @@ const mountComponent = IS_MODERN_SVELTE ? mountModern : mountLegacy
 /**
  * Render a Svelte component into the document.
  *
- * @template {import('./types.js').Component} C
- * @param {import('./types.js').ComponentType<C>} Component
- * @param {import('./types.js').MountOptions<C>} options
+ * @template {import('../types.js').Component} C
+ * @param {import('../types.js').ComponentImport<C>} Component
+ * @param {import('../types.js').MountOptions<C>} options
  * @returns {{
  *   component: C
  *   unmount: () => void
- *   rerender: (props: Partial<import('./types.js').Props<C>>) => Promise<void>
+ *   rerender: (props: Partial<import('../types.js').Props<C>>) => Promise<void>
  * }}
  */
 const mount = (Component, options) => {
-  const { component, unmount, rerender } = mountComponent(Component, options)
+  const { component, unmount, rerender } = mountComponent(
+    'default' in Component ? Component.default : Component,
+    options
+  )
 
   return {
     component,
     unmount,
     rerender: async (props) => {
+      if ('props' in props) {
+        console.warn(
+          'rerender({ props: { ... } }) deprecated, use rerender({ ... }) instead'
+        )
+        props = props.props
+      }
+
       rerender(props)
       // Await the next tick for Svelte 4, which cannot flush changes synchronously
       await Svelte.tick()

packages/svelte/src/core/index.js renamed to packages/svelte-core/src/index.js

@@ -8,11 +8,10 @@
  * @param {Props} initialProps
  * @returns {[Props, (nextProps: Partial<Props>) => void]}
  */
-const createProps = (initialProps) => {
-  const targetProps = initialProps ?? {}
-  let currentProps = $state.raw(targetProps)
+const createProps = (initialProps = {}) => {
+  let currentProps = $state.raw(initialProps)
 
-  const props = new Proxy(targetProps, {
+  const props = new Proxy(initialProps, {
     get(_, key) {
       return currentProps[key]
     },

packages/svelte/src/core/mount.js renamed to packages/svelte-core/src/mount.js

@@ -27,9 +27,9 @@ class UnknownSvelteOptionsError extends TypeError {
 /**
  * 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>>}
+ * @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) =>
@@ -55,16 +55,16 @@ const validateOptions = (options) => {
 /**
  * Set up the document to render a component.
  *
- * @template {import('./types.js').Component} C
- * @param {import('./types.js').ComponentOptions<C>} componentOptions - props or mount options
+ * @template {import('../types.js').Component} C
+ * @param {import('../types.js').ComponentOptions<C>} componentOptions - 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>
+ *   mountOptions: import('../types.js').MountOptions<C>
  * }}
  */
-const setup = (componentOptions, setupOptions) => {
+const setup = (componentOptions, setupOptions = {}) => {
   const mountOptions = validateOptions(componentOptions)
 
   const baseElement =