feat: expose el prop for DOM manipulation (#244)

Co-authored-by: Hunter Johnston <johnstonhuntera@gmail.com>
huntabyte · Dec 28, 2023 · 9a0d34d · 9a0d34d
1 parent 37de976
commit 9a0d34d
Show file tree

Hide file tree

Showing 239 changed files with 956 additions and 569 deletions.
diff --git a/.changeset/selfish-eels-promise.md b/.changeset/selfish-eels-promise.md
@@ -0,0 +1,5 @@
+---
+"bits-ui": minor
+---
+
+Expose `el` prop for all components to allow binding & interacting with the underlying element  
diff --git a/src/content/api-reference/accordion.ts b/src/content/api-reference/accordion.ts
@@ -1,8 +1,8 @@
 import type { APISchema } from "@/types";
 import * as C from "@/content/constants.js";
-import { union, enums, asChild, transitionProps } from "@/content/api-reference/helpers.js";
+import { union, enums, transitionProps } from "@/content/api-reference/helpers.js";
 import type * as Accordion from "$lib/bits/accordion/_types.js";
-import { builderAndAttrsSlotProps } from "./helpers";
+import { builderAndAttrsSlotProps, domElProps } from "./helpers";
 
 const root: APISchema<Accordion.Props<false>> = {
 	title: "Root",
@@ -32,7 +32,7 @@ const root: APISchema<Accordion.Props<false>> = {
 			},
 			description: "A callback function called when the active accordion item value changes."
 		},
-		asChild
+		...domElProps("HTMLDivElement")
 	},
 	slotProps: {
 		...builderAndAttrsSlotProps
@@ -66,7 +66,7 @@ const item: APISchema<Accordion.ItemProps> = {
 			type: "boolean",
 			description: "Whether or not the accordion item is disabled."
 		},
-		asChild
+		...domElProps("HTMLDivElement")
 	},
 	slotProps: {
 		...builderAndAttrsSlotProps
@@ -93,7 +93,7 @@ const item: APISchema<Accordion.ItemProps> = {
 const trigger: APISchema<Accordion.TriggerProps> = {
 	title: "Trigger",
 	description: "The accordion item trigger, which opens and closes the accordion item.",
-	props: { asChild },
+	props: { ...domElProps("HTMLButtonElement") },
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -120,7 +120,7 @@ const trigger: APISchema<Accordion.TriggerProps> = {
 const content: APISchema<Accordion.ContentProps> = {
 	title: "Content",
 	description: "The accordion item content, which is displayed when the item is open.",
-	props: { ...transitionProps, asChild },
+	props: { ...transitionProps, ...domElProps("HTMLDivElement") },
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -156,7 +156,7 @@ const header: APISchema<Accordion.HeaderProps> = {
 			description:
 				"The heading level to use for the header. This will be set as the `aria-level` attribute."
 		},
-		asChild
+		...domElProps("HTMLDivElement")
 	},
 	slotProps: {
 		...builderAndAttrsSlotProps

diff --git a/src/content/api-reference/alert-dialog.ts b/src/content/api-reference/alert-dialog.ts
@@ -1,15 +1,15 @@
 import type { APISchema } from "@/types/api.js";
 import {
-	asChild,
+	domElProps,
 	enums,
 	idsSlotProp,
 	portalProp,
-	transitionProps
+	transitionProps,
+	builderAndAttrsSlotProps
 } from "@/content/api-reference/helpers.js";
 import * as C from "@/content/constants.js";
 import { focusProp } from "@/content/api-reference/extended-types/index.js";
 import type * as AlertDialog from "$lib/bits/alert-dialog/_types.js";
-import { builderAndAttrsSlotProps } from "./helpers";
 
 const root: APISchema<AlertDialog.Props> = {
 	title: "Root",
@@ -60,7 +60,7 @@ const root: APISchema<AlertDialog.Props> = {
 const action: APISchema<AlertDialog.ActionProps> = {
 	title: "Action",
 	description: "A button used to close the alert dialog by taking an action.",
-	props: { asChild },
+	props: domElProps("HTMLButtonElement"),
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -73,7 +73,7 @@ const action: APISchema<AlertDialog.ActionProps> = {
 const cancel: APISchema<AlertDialog.CancelProps> = {
 	title: "Cancel",
 	description: "A button used to close the alert dialog without taking an action.",
-	props: { asChild },
+	props: domElProps("HTMLButtonElement"),
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -86,7 +86,7 @@ const cancel: APISchema<AlertDialog.CancelProps> = {
 const content: APISchema<AlertDialog.ContentProps> = {
 	title: "Content",
 	description: "The content displayed within the alert dialog modal.",
-	props: { ...transitionProps, asChild },
+	props: { ...transitionProps, ...domElProps("HTMLDivElement") },
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -106,7 +106,7 @@ const title: APISchema<AlertDialog.TitleProps> = {
 	title: "Title",
 	description: "An accessibile title for the alert dialog.",
 	props: {
-		asChild,
+		...domElProps("HTMLHeadingElement"),
 		level: {
 			type: {
 				type: "enum",
@@ -127,7 +127,7 @@ const title: APISchema<AlertDialog.TitleProps> = {
 const description: APISchema<AlertDialog.DescriptionProps> = {
 	title: "Description",
 	description: "An accessibile description for the alert dialog.",
-	props: { asChild },
+	props: domElProps("HTMLDivElement"),
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -140,7 +140,7 @@ const description: APISchema<AlertDialog.DescriptionProps> = {
 const trigger: APISchema<AlertDialog.TriggerProps> = {
 	title: "Trigger",
 	description: "The element which opens the alert dialog on press.",
-	props: { asChild },
+	props: domElProps("HTMLButtonElement"),
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -153,7 +153,7 @@ const trigger: APISchema<AlertDialog.TriggerProps> = {
 const overlay: APISchema<AlertDialog.OverlayProps> = {
 	title: "Overlay",
 	description: "An overlay which covers the body when the alert dialog is open.",
-	props: { ...transitionProps, asChild },
+	props: { ...transitionProps, ...domElProps("HTMLDivElement") },
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{

diff --git a/src/content/api-reference/aspect-ratio.ts b/src/content/api-reference/aspect-ratio.ts
@@ -1,6 +1,7 @@
 import type { APISchema } from "@/types";
 import type * as AspectRatio from "$lib/bits/aspect-ratio/_types.js";
 import * as C from "@/content/constants";
+import { domElProps } from "./helpers";
 
 const root: APISchema<AspectRatio.Props> = {
 	title: "Root",
@@ -10,7 +11,8 @@ const root: APISchema<AspectRatio.Props> = {
 			type: C.NUMBER,
 			default: "1",
 			description: "The desired aspect ratio."
-		}
+		},
+		...domElProps("HTMLDivElement")
 	},
 	dataAttributes: [
 		{

diff --git a/src/content/api-reference/avatar.ts b/src/content/api-reference/avatar.ts
@@ -1,8 +1,8 @@
 import type { APISchema } from "@/types";
-import { asChild, attrsSlotProp, enums } from "@/content/api-reference/helpers.js";
+import { attrsSlotProp, enums } from "@/content/api-reference/helpers.js";
 import type * as Avatar from "$lib/bits/avatar/_types";
 import * as C from "@/content/constants.js";
-import { builderAndAttrsSlotProps } from "./helpers";
+import { builderAndAttrsSlotProps, domElProps } from "./helpers";
 
 export const root: APISchema<Avatar.Props> = {
 	title: "Root",
@@ -29,7 +29,7 @@ export const root: APISchema<Avatar.Props> = {
 			},
 			description: "A callback function called when the loading status of the image changes."
 		},
-		asChild
+		...domElProps("HTMLDivElement")
 	},
 	slotProps: {
 		attrs: attrsSlotProp
@@ -45,7 +45,7 @@ export const root: APISchema<Avatar.Props> = {
 export const image: APISchema<Avatar.ImageProps> = {
 	title: "Image",
 	description: "The avatar image displayed once it has loaded.",
-	props: { asChild },
+	props: domElProps("HTMLImageElement"),
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -58,7 +58,7 @@ export const image: APISchema<Avatar.ImageProps> = {
 export const fallback: APISchema<Avatar.FallbackProps> = {
 	title: "Fallback",
 	description: "The fallback displayed while the avatar image is loading or if it fails to load",
-	props: { asChild },
+	props: domElProps("HTMLSpanElement"),
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{

diff --git a/src/content/api-reference/calendar.ts b/src/content/api-reference/calendar.ts
@@ -1,13 +1,8 @@
 import type { APISchema } from "@/types";
 import * as C from "@/content/constants.js";
-import {
-	asChild,
-	weekdaysSlotProp,
-	enums,
-	monthsSlotProp
-} from "@/content/api-reference/helpers.js";
+import { weekdaysSlotProp, enums, monthsSlotProp } from "@/content/api-reference/helpers.js";
 import type * as Calendar from "$lib/bits/calendar/_types.js";
-import { attrsSlotProp, builderAndAttrsSlotProps } from "./helpers";
+import { attrsSlotProp, builderAndAttrsSlotProps, domElProps } from "./helpers";
 
 export const root: APISchema<Calendar.Props> = {
 	title: "Root",
@@ -123,7 +118,7 @@ export const root: APISchema<Calendar.Props> = {
 				"If `true`, the calendar will focus the selected day, today, or the first day of the month in that order depending on what is visible when the calendar is mounted.",
 			default: C.FALSE
 		},
-		asChild
+		...domElProps("HTMLDivElement")
 	},
 	slotProps: {
 		months: monthsSlotProp,
@@ -154,11 +149,11 @@ export const cell: APISchema<Calendar.CellProps> = {
 	title: "Cell",
 	description: "A cell in the calendar grid.",
 	props: {
-		asChild,
 		date: {
 			type: "DateValue",
 			description: "The date for the cell."
-		}
+		},
+		...domElProps("HTMLTableCellElement")
 	},
 	slotProps: {
 		attrs: attrsSlotProp
@@ -179,15 +174,15 @@ export const day: APISchema<Calendar.DayProps> = {
 	title: "Day",
 	description: "A day in the calendar grid.",
 	props: {
-		asChild,
 		date: {
 			type: "DateValue",
 			description: "The date for the cell."
 		},
 		month: {
 			type: "DateValue",
 			description: "The current month the date is being displayed in."
-		}
+		},
+		...domElProps("HTMLDivElement")
 	},
 	slotProps: {
 		disabled: {
@@ -247,9 +242,7 @@ export const day: APISchema<Calendar.DayProps> = {
 export const grid: APISchema<Calendar.GridProps> = {
 	title: "Grid",
 	description: "The grid of dates in the calendar, typically representing a month.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLTableElement"),
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
 		{
@@ -262,9 +255,7 @@ export const grid: APISchema<Calendar.GridProps> = {
 export const gridBody: APISchema<Calendar.GridBodyProps> = {
 	title: "GridBody",
 	description: "The body of the grid of dates in the calendar.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLTableSectionElement"),
 	slotProps: { attrs: attrsSlotProp },
 	dataAttributes: [
 		{
@@ -277,9 +268,7 @@ export const gridBody: APISchema<Calendar.GridBodyProps> = {
 export const gridHead: APISchema<Calendar.GridHeadProps> = {
 	title: "GridHead",
 	description: "The head of the grid of dates in the calendar.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLTableSectionElement"),
 	slotProps: {
 		attrs: attrsSlotProp
 	},
@@ -294,9 +283,7 @@ export const gridHead: APISchema<Calendar.GridHeadProps> = {
 export const gridRow: APISchema<Calendar.GridRowProps> = {
 	title: "GridRow",
 	description: "A row in the grid of dates in the calendar.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLTableRowElement"),
 	slotProps: {
 		attrs: attrsSlotProp
 	},
@@ -311,9 +298,7 @@ export const gridRow: APISchema<Calendar.GridRowProps> = {
 export const headCell: APISchema<Calendar.HeadCellProps> = {
 	title: "HeadCell",
 	description: "A cell in the head of the grid of dates in the calendar.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLTableCellElement"),
 	slotProps: {
 		attrs: attrsSlotProp
 	},
@@ -328,9 +313,7 @@ export const headCell: APISchema<Calendar.HeadCellProps> = {
 export const header: APISchema<Calendar.HeaderProps> = {
 	title: "Header",
 	description: "The header of the calendar.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLElement"),
 	slotProps: {
 		attrs: attrsSlotProp
 	},
@@ -345,9 +328,7 @@ export const header: APISchema<Calendar.HeaderProps> = {
 export const heading: APISchema<Calendar.HeadingProps> = {
 	title: "Heading",
 	description: "The heading of the calendar.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLDivElement"),
 	slotProps: {
 		...builderAndAttrsSlotProps,
 		headingValue: {
@@ -366,9 +347,7 @@ export const heading: APISchema<Calendar.HeadingProps> = {
 export const nextButton: APISchema<Calendar.NextButtonProps> = {
 	title: "NextButton",
 	description: "The next button of the calendar.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLButtonElement"),
 	slotProps: {
 		...builderAndAttrsSlotProps
 	},
@@ -383,9 +362,7 @@ export const nextButton: APISchema<Calendar.NextButtonProps> = {
 export const prevButton: APISchema<Calendar.PrevButtonProps> = {
 	title: "PrevButton",
 	description: "The previous button of the calendar.",
-	props: {
-		asChild
-	},
+	props: domElProps("HTMLButtonElement"),
 	slotProps: {
 		...builderAndAttrsSlotProps
 	},

diff --git a/src/content/api-reference/checkbox.ts b/src/content/api-reference/checkbox.ts
@@ -1,8 +1,8 @@
-import { asChild, attrsSlotProp, enums, union } from "./helpers.js";
+import { attrsSlotProp, enums, union } from "./helpers.js";
 import type { APISchema } from "@/types";
 import type * as Checkbox from "$lib/bits/checkbox/_types";
 import * as C from "@/content/constants";
-import { builderAndAttrsSlotProps } from "./helpers";
+import { builderAndAttrsSlotProps, domElProps } from "./helpers";
 
 export const root: APISchema<Checkbox.Props> = {
 	title: "Root",
@@ -43,7 +43,7 @@ export const root: APISchema<Checkbox.Props> = {
 			type: C.STRING,
 			description: "The value of the checkbox. This is used for form submission."
 		},
-		asChild
+		...domElProps("HTMLButtonElement")
 	},
 	slotProps: { ...builderAndAttrsSlotProps },
 	dataAttributes: [
@@ -88,7 +88,7 @@ export const indicator: APISchema<Checkbox.IndicatorProps> = {
 	title: "Indicator",
 	description:
 		"A component which passes `isChecked` and `isIndeterminate` slot props to its children. This is useful for rendering the checkbox's indicator icon depending on its state.",
-	props: { asChild },
+	props: domElProps("HTMLDivElement"),
 	slotProps: {
 		isChecked: {
 			type: C.BOOLEAN,