From ce49f50ceeff9bc2f171e18126aa126ff73c508c Mon Sep 17 00:00:00 2001
From: Hunter Johnston <64506580+huntabyte@users.noreply.github.com>
Date: Wed, 2 Oct 2024 20:28:00 -0400
Subject: [PATCH] next: `Portal` utility component (#716)

---
 .changeset/early-points-study.md              |  5 ++
 packages/bits-ui/package.json                 |  3 -
 packages/bits-ui/src/lib/bits/index.ts        |  1 +
 .../lib/bits/utilities/portal/portal.svelte   | 17 ++--
 .../src/lib/bits/utilities/portal/types.ts    |  5 +-
 .../bits-ui/src/lib/internal/cssToStyleObj.ts |  2 +-
 packages/bits-ui/src/lib/internal/strings.ts  | 82 +++++++++++++++++++
 packages/bits-ui/src/lib/internal/style.ts    |  2 +-
 .../bits-ui/src/lib/internal/styleToCSS.ts    | 29 +++++++
 .../shared/style-object-to-css-string.d.ts    | 10 ---
 packages/bits-ui/src/lib/types.ts             |  1 +
 pnpm-lock.yaml                                |  9 --
 sites/docs/content/utilities/portal.md        | 56 +++++++++++++
 13 files changed, 191 insertions(+), 31 deletions(-)
 create mode 100644 .changeset/early-points-study.md
 create mode 100644 packages/bits-ui/src/lib/internal/strings.ts
 create mode 100644 packages/bits-ui/src/lib/internal/styleToCSS.ts
 delete mode 100644 packages/bits-ui/src/lib/shared/style-object-to-css-string.d.ts
 create mode 100644 sites/docs/content/utilities/portal.md

diff --git a/.changeset/early-points-study.md b/.changeset/early-points-study.md
new file mode 100644
index 000000000..38a79506f
--- /dev/null
+++ b/.changeset/early-points-study.md
@@ -0,0 +1,5 @@
+---
+"bits-ui": patch
+---
+
+feat: export and document `Portal` utility component
diff --git a/packages/bits-ui/package.json b/packages/bits-ui/package.json
index 9f511cecc..048a3702e 100644
--- a/packages/bits-ui/package.json
+++ b/packages/bits-ui/package.json
@@ -60,10 +60,7 @@
 		"@internationalized/date": "^3.5.4",
 		"clsx": "^2.1.1",
 		"esm-env": "^1.0.0",
-		"nanoid": "^5.0.7",
 		"runed": "^0.15.2",
-		"scule": "^1.3.0",
-		"style-object-to-css-string": "^1.1.3",
 		"style-to-object": "^1.0.6",
 		"svelte-toolbelt": "^0.3.1"
 	},
diff --git a/packages/bits-ui/src/lib/bits/index.ts b/packages/bits-ui/src/lib/bits/index.ts
index c078f6475..0fb808049 100644
--- a/packages/bits-ui/src/lib/bits/index.ts
+++ b/packages/bits-ui/src/lib/bits/index.ts
@@ -36,3 +36,4 @@ export * as Toggle from "./toggle/index.js";
 export * as ToggleGroup from "./toggle-group/index.js";
 export * as Toolbar from "./toolbar/index.js";
 export * as Tooltip from "./tooltip/index.js";
+export { default as Portal } from "./utilities/portal/portal.svelte";
diff --git a/packages/bits-ui/src/lib/bits/utilities/portal/portal.svelte b/packages/bits-ui/src/lib/bits/utilities/portal/portal.svelte
index 840771663..d10d5cefc 100644
--- a/packages/bits-ui/src/lib/bits/utilities/portal/portal.svelte
+++ b/packages/bits-ui/src/lib/bits/utilities/portal/portal.svelte
@@ -1,5 +1,6 @@
 <script lang="ts">
 	import { getAllContexts, mount, unmount, untrack } from "svelte";
+	import { DEV } from "esm-env";
 	import PortalConsumer from "./portal-consumer.svelte";
 	import type { PortalProps } from "./types.js";
 	import { isBrowser } from "$lib/internal/is.js";
@@ -16,16 +17,20 @@
 		if (typeof to === "string") {
 			localTarget = document.querySelector(to);
 			if (localTarget === null) {
-				throw new Error(`Target element "${to}" not found.`);
+				if (DEV) {
+					throw new Error(`Target element "${to}" not found.`);
+				}
 			}
 		} else if (to instanceof HTMLElement || to instanceof DocumentFragment) {
 			localTarget = to;
 		} else {
-			throw new TypeError(
-				`Unknown portal target type: ${
-					to === null ? "null" : typeof to
-				}. Allowed types: string (CSS selector) or HTMLElement.`
-			);
+			if (DEV) {
+				throw new TypeError(
+					`Unknown portal target type: ${
+						to === null ? "null" : typeof to
+					}. Allowed types: string (query selector), HTMLElement, or DocumentFragment.`
+				);
+			}
 		}
 
 		return localTarget;
diff --git a/packages/bits-ui/src/lib/bits/utilities/portal/types.ts b/packages/bits-ui/src/lib/bits/utilities/portal/types.ts
index 2ce5b8ae2..d046d2682 100644
--- a/packages/bits-ui/src/lib/bits/utilities/portal/types.ts
+++ b/packages/bits-ui/src/lib/bits/utilities/portal/types.ts
@@ -9,11 +9,14 @@ export type PortalProps = {
 	to?: HTMLElement | string | DocumentFragment;
 
 	/**
-	 * Disable portaling and render the component inline
+	 * Disable portalling and render the component inline
 	 *
 	 * @defaultValue false
 	 */
 	disabled?: boolean;
 
+	/**
+	 * The children content to render within the portal.
+	 */
 	children?: Snippet;
 };
diff --git a/packages/bits-ui/src/lib/internal/cssToStyleObj.ts b/packages/bits-ui/src/lib/internal/cssToStyleObj.ts
index 98dc95ec8..847392d18 100644
--- a/packages/bits-ui/src/lib/internal/cssToStyleObj.ts
+++ b/packages/bits-ui/src/lib/internal/cssToStyleObj.ts
@@ -1,5 +1,5 @@
 import parse from "style-to-object";
-import { camelCase, pascalCase } from "scule";
+import { camelCase, pascalCase } from "$lib/internal/strings.js";
 import type { StyleProperties } from "$lib/shared/index.js";
 
 export function cssToStyleObj(css: string | null | undefined): StyleProperties {
diff --git a/packages/bits-ui/src/lib/internal/strings.ts b/packages/bits-ui/src/lib/internal/strings.ts
new file mode 100644
index 000000000..f719597ab
--- /dev/null
+++ b/packages/bits-ui/src/lib/internal/strings.ts
@@ -0,0 +1,82 @@
+const NUMBER_CHAR_RE = /\d/;
+const STR_SPLITTERS = ["-", "_", "/", "."];
+
+function isUppercase(char = ""): boolean | undefined {
+	if (NUMBER_CHAR_RE.test(char)) return undefined;
+	return char !== char.toLowerCase();
+}
+
+function splitByCase(str: string) {
+	const parts: string[] = [];
+
+	let buff = "";
+
+	let previousUpper: boolean | undefined;
+	let previousSplitter: boolean | undefined;
+
+	for (const char of str) {
+		// Splitter
+		const isSplitter = STR_SPLITTERS.includes(char);
+		if (isSplitter === true) {
+			parts.push(buff);
+			buff = "";
+			previousUpper = undefined;
+			continue;
+		}
+
+		const isUpper = isUppercase(char);
+		if (previousSplitter === false) {
+			// Case rising edge
+			if (previousUpper === false && isUpper === true) {
+				parts.push(buff);
+				buff = char;
+				previousUpper = isUpper;
+				continue;
+			}
+			// Case falling edge
+			if (previousUpper === true && isUpper === false && buff.length > 1) {
+				const lastChar = buff.at(-1);
+				parts.push(buff.slice(0, Math.max(0, buff.length - 1)));
+				buff = lastChar + char;
+				previousUpper = isUpper;
+				continue;
+			}
+		}
+
+		// Normal char
+		buff += char;
+		previousUpper = isUpper;
+		previousSplitter = isSplitter;
+	}
+
+	parts.push(buff);
+
+	return parts;
+}
+
+export function pascalCase(str?: string) {
+	if (!str) return "";
+	return splitByCase(str)
+		.map((p) => upperFirst(p))
+		.join("");
+}
+
+export function camelCase(str?: string) {
+	return lowerFirst(pascalCase(str || ""));
+}
+
+export function kebabCase(str?: string) {
+	return str
+		? splitByCase(str)
+				.map((p) => p.toLowerCase())
+				.join("-")
+		: "";
+}
+
+function upperFirst(str: string) {
+	return str ? str[0]!.toUpperCase() + str.slice(1) : "";
+}
+
+function lowerFirst(str: string) {
+	return str ? str[0]!.toLowerCase() + str.slice(1) : "";
+}
diff --git a/packages/bits-ui/src/lib/internal/style.ts b/packages/bits-ui/src/lib/internal/style.ts
index d97c74b3d..c4e2cfab4 100644
--- a/packages/bits-ui/src/lib/internal/style.ts
+++ b/packages/bits-ui/src/lib/internal/style.ts
@@ -1,4 +1,4 @@
-import styleToCSS from "style-object-to-css-string";
+import { styleToCSS } from "./styleToCSS.js";
 import type { StyleProperties } from "$lib/shared/index.js";
 
 export function styleToString(style: StyleProperties = {}): string {
diff --git a/packages/bits-ui/src/lib/internal/styleToCSS.ts b/packages/bits-ui/src/lib/internal/styleToCSS.ts
new file mode 100644
index 000000000..9212df4b1
--- /dev/null
+++ b/packages/bits-ui/src/lib/internal/styleToCSS.ts
@@ -0,0 +1,29 @@
+function createParser(matcher: string | RegExp, replacer: (match: string) => string) {
+	const regex = RegExp(matcher, "g");
+	return (str: string): string => {
+		// throw an error if not a string
+		if (typeof str !== "string") {
+			throw new TypeError(`expected an argument of type string, but got ${typeof str}`);
+		}
+
+		// if no match between string and matcher
+		if (!str.match(regex)) return str;
+
+		// executes the replacer function for each match
+		return str.replace(regex, replacer);
+	};
+}
+
+const camelToKebab = createParser(/[A-Z]/, (match) => `-${match.toLowerCase()}`);
+
+export function styleToCSS(styleObj: object) {
+	if (!styleObj || typeof styleObj !== "object" || Array.isArray(styleObj)) {
+		throw new TypeError(`expected an argument of type object, but got ${typeof styleObj}`);
+	}
+	return Object.keys(styleObj)
+		.map(
+			(property) =>
+				`${camelToKebab(property)}: ${styleObj[property as keyof typeof styleObj]};`
+		)
+		.join("\n");
+}
diff --git a/packages/bits-ui/src/lib/shared/style-object-to-css-string.d.ts b/packages/bits-ui/src/lib/shared/style-object-to-css-string.d.ts
deleted file mode 100644
index 9a159991e..000000000
--- a/packages/bits-ui/src/lib/shared/style-object-to-css-string.d.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-declare module "style-object-to-css-string" {
-	export default objToString;
-	/**
-	 * Translate a style object into a CSS string
-	 * @param {object} styleObj - The object to run a particular parser against
-	 * @returns {string} - The CSS string
-	 */
-	// eslint-disable-next-line ts/no-explicit-any
-	declare function objToString(styleObj: any): string;
-}
diff --git a/packages/bits-ui/src/lib/types.ts b/packages/bits-ui/src/lib/types.ts
index da8832c74..c635858db 100644
--- a/packages/bits-ui/src/lib/types.ts
+++ b/packages/bits-ui/src/lib/types.ts
@@ -36,3 +36,4 @@ export type * from "$lib/bits/toggle/types.js";
 export type * from "$lib/bits/toggle-group/types.js";
 export type * from "$lib/bits/toolbar/types.js";
 export type * from "$lib/bits/tooltip/types.js";
+export type { PortalProps } from "$lib/bits/utilities/portal/types.js";
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 80bf8b3ac..4b3b87557 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -62,18 +62,9 @@ importers:
       esm-env:
         specifier: ^1.0.0
         version: 1.0.0
-      nanoid:
-        specifier: ^5.0.7
-        version: 5.0.7
       runed:
         specifier: ^0.15.2
         version: 0.15.2(svelte@5.0.0-next.260)
-      scule:
-        specifier: ^1.3.0
-        version: 1.3.0
-      style-object-to-css-string:
-        specifier: ^1.1.3
-        version: 1.1.3
       style-to-object:
         specifier: ^1.0.6
         version: 1.0.6
diff --git a/sites/docs/content/utilities/portal.md b/sites/docs/content/utilities/portal.md
new file mode 100644
index 000000000..5b05e80bf
--- /dev/null
+++ b/sites/docs/content/utilities/portal.md
@@ -0,0 +1,56 @@
+---
+title: Portal
+description: A component that renders its children in a portal, preventing layout issues in complex UI structures.
+---
+
+## Overview
+
+The Portal component is a utility component that renders its children in a portal, preventing layout issues in complex UI structures. This component is used for the various Bits UI component that have a `Portal` sub-component.
+
+## Usage
+
+### Default behavior
+
+By default, the `Portal` component will render its children in the `body` element.
+
+```svelte
+<script lang="ts">
+	import { Portal } from "bits-ui";
+</script>
+
+<Portal>
+	<div>This content will be portalled to the body</div>
+</Portal>
+```
+
+### Custom target
+
+You can use the `to` prop to specify a custom target element or selector to render the content to.
+
+```svelte
+<script lang="ts">
+	import { Portal } from "bits-ui";
+</script>
+
+<div id="custom-target"></div>
+
+<div>
+	<Portal to="#custom-target">
+		<div>This content will be portalled to the #custom-target element</div>
+	</Portal>
+</div>
+```
+
+### Disable
+
+You can use the `disabled` prop to disable the portal behavior.
+
+```svelte
+<script lang="ts">
+	import { Portal } from "bits-ui";
+</script>
+
+<Portal disabled>
+	<div>This content will not be portalled</div>
+</Portal>
+```