refactor: new polymorphic implementation

apps/docs/src/examples/select.tsx

@@ -1,4 +1,4 @@
-import { As, Select } from "@kobalte/core";
+import { Select } from "@kobalte/core";
 import { createVirtualizer } from "@tanstack/solid-virtual";
 import { For, createSignal } from "solid-js";
 
@@ -377,46 +377,44 @@ export function MultipleSelectionExample() {
 				<Select.Trigger
 					class={`${style.select__trigger} ${style.select__trigger_multi}`}
 					aria-label="Fruits"
-					asChild
+					as="div"
 				>
-					<As component="div">
-						<Select.Value<string> class={style.select__value}>
-							{(state) => (
-								<>
-									<div class="flex items-center gap-2 flex-wrap">
-										<For each={state.selectedOptions()}>
-											{(option) => (
-												<span
-													class="bg-zinc-100 dark:bg-zinc-700 text-sm px-2 py-0.5 rounded inline-flex items-center gap-x-2"
-													onPointerDown={(e) => e.stopPropagation()}
+					<Select.Value<string> class={style.select__value}>
+						{(state) => (
+							<>
+								<div class="flex items-center gap-2 flex-wrap">
+									<For each={state.selectedOptions()}>
+										{(option) => (
+											<span
+												class="bg-zinc-100 dark:bg-zinc-700 text-sm px-2 py-0.5 rounded inline-flex items-center gap-x-2"
+												onPointerDown={(e) => e.stopPropagation()}
+											>
+												{option}
+												<button
+													type="button"
+													onClick={() => state.remove(option)}
+													class="rounded-full hover:bg-zinc-300 dark:hover:bg-zinc-600 p-1"
 												>
-													{option}
-													<button
-														type="button"
-														onClick={() => state.remove(option)}
-														class="rounded-full hover:bg-zinc-300 dark:hover:bg-zinc-600 p-1"
-													>
-														<CrossIcon class="h3 w-3" />
-													</button>
-												</span>
-											)}
-										</For>
-									</div>
-									<button
-										type="button"
-										onPointerDown={(e) => e.stopPropagation()}
-										onClick={state.clear}
-										class="ml-auto mr-2 rounded-full hover:bg-zinc-100 dark:hover:bg-zinc-600 p-1"
-									>
-										<CrossIcon class="h-3.5 w-3.5" />
-									</button>
-								</>
-							)}
-						</Select.Value>
-						<Select.Icon class={style.select__icon}>
-							<CaretSortIcon />
-						</Select.Icon>
-					</As>
+													<CrossIcon class="h3 w-3" />
+												</button>
+											</span>
+										)}
+									</For>
+								</div>
+								<button
+									type="button"
+									onPointerDown={(e) => e.stopPropagation()}
+									onClick={state.clear}
+									class="ml-auto mr-2 rounded-full hover:bg-zinc-100 dark:hover:bg-zinc-600 p-1"
+								>
+									<CrossIcon class="h-3.5 w-3.5" />
+								</button>
+							</>
+						)}
+					</Select.Value>
+					<Select.Icon class={style.select__icon}>
+						<CaretSortIcon />
+					</Select.Icon>
 				</Select.Trigger>
 				<Select.Portal>
 					<Select.Content class={style.select__content}>

apps/docs/src/routes/docs/core.tsx

@@ -26,11 +26,11 @@ const CORE_NAV_SECTIONS: NavSection[] = [
 			{
 				title: "Polymorphism",
 				href: "/docs/core/overview/polymorphism",
+				status: "updated",
 			},
 			{
 				title: "Server side rendering",
 				href: "/docs/core/overview/ssr",
-				status: "updated",
 			},
 		],
 	},

apps/docs/src/routes/docs/core/components/select.mdx

@@ -652,7 +652,7 @@ The `multiple` prop can be used to create a select that allow multi-selection. I
 
 The `Select.Value` children _render prop_ expose an array of selected options, and two method for removing an option from the selection and clear the selection.
 
-Additionally, the example below uses the `asChild` pattern to render a `div` for the `Select.Trigger` since HTML button can't contain interactive elements according to the [W3C](https://html.spec.whatwg.org/multipage/form-elements.html#the-button-element).
+Additionally, the example below uses the `as` prop to render a `div` for the `Select.Trigger` since HTML button can't contain interactive elements according to the [W3C](https://html.spec.whatwg.org/multipage/form-elements.html#the-button-element).
 
 <Preview>
 	<MultipleSelectionExample />
@@ -681,33 +681,31 @@ function MultipleSelectionExample() {
 					</Select.Item>
 				)}
 			>
-				<Select.Trigger aria-label="Fruits" asChild>
-					<As component="div">
-						<Select.Value<string>>
-							{state => (
-								<>
-									<div>
-										<For each={state.selectedOptions()}>
-											{option => (
-												<span onPointerDown={e => e.stopPropagation()}>
-													{option}
-													<button onClick={() => state.remove(option)}>
-														<CrossIcon />
-													</button>
-												</span>
-											)}
-										</For>
-									</div>
-									<button onPointerDown={e => e.stopPropagation()} onClick={state.clear}>
-										<CrossIcon />
-									</button>
-								</>
-							)}
-						</Select.Value>
-						<Select.Icon>
-							<CaretSortIcon />
-						</Select.Icon>
-					</As>
+				<Select.Trigger aria-label="Fruits" as="div">
+					<Select.Value<string>>
+						{state => (
+							<>
+								<div>
+									<For each={state.selectedOptions()}>
+										{option => (
+											<span onPointerDown={e => e.stopPropagation()}>
+												{option}
+												<button onClick={() => state.remove(option)}>
+													<CrossIcon />
+												</button>
+											</span>
+										)}
+									</For>
+								</div>
+								<button onPointerDown={e => e.stopPropagation()} onClick={state.clear}>
+									<CrossIcon />
+								</button>
+							</>
+						)}
+					</Select.Value>
+					<Select.Icon>
+						<CaretSortIcon />
+					</Select.Icon>
 				</Select.Trigger>
 				<Select.Portal>
 					<Select.Content>

apps/docs/src/routes/docs/core/overview/polymorphism.mdx

@@ -1,6 +1,6 @@
 # Polymorphism
 
-All component parts that render a DOM element have an `as` and a `asChild` prop.
+All component parts that render a DOM element have an `as` prop.
 
 ## The `as` prop
 
@@ -30,19 +30,20 @@ function App() {
 }
 ```
 
-## The `asChild` prop
+## The `as` prop callback
 
-For more advanced use cases the `asChild` prop and the `<As>` component can be used.
-The main reason to use `asChild` over the `as` prop is being able to set props without interfering with Kobalte.
+For more advanced use cases the `as` prop can accept a callback.
+The main reason to use a callback over the normal `as` prop is being able to set props without interfering with Kobalte.
 
-When using this pattern the following rules apply to the component with the `asChild` prop, and it's child `<As>` component:
+When using this pattern the following rules apply to the callback:
 
-- CSS classes are combined.
-- Props are combined, if same attribute exists the one from `<As>` win.
-- Event handlers are chained, the one from `<As>` get called first.
+- You must spread the props forwarded to your callback onto your node/component.
+- Custom props are passed as is from the parent.
+- Kobalte options are not passed to the callback, only the resulting html attributes.
+- You should set your event handlers on the parent and not inside your callback.
 
 ```tsx {15}
-import { As, Tabs as KTabs } from "@kobalte/core";
+import { Tabs as KTabs } from "@kobalte/core";
 import { MyCustomButton } from "./components";
 
 function App() {
@@ -55,15 +56,147 @@ function App() {
 				</KTabs.Trigger>
 
 				{/* The `value` prop is used by Kobalte and not passed to MyCustomButton */}
-				<KTabs.Trigger value="one" asChild>
-					{/* The `value` prop is directly passed to MyCustomButton */}
-					<As component={MyCustomButton} value="custom">
-						Custom Button Trigger
-					</As>
+				<KTabs.Trigger
+					value="one"
+					as={props => (
+						// The `value` prop is directly passed to MyCustomButton
+						<MyCustomButton value="custom" {...props} />
+					)}
+				>
+					Custom Button Trigger
 				</KTabs.Trigger>
 			</KTabs.List>
 			<KTabs.Content value="one">Content one</KTabs.Content>
 		</KTabs.Root>
 	);
 }
 ```
+
+You can optionally use a type helper to get the exact types passed to your callback:
+
+```tsx {4}
+import { Tabs as KTabs, PolymorphicCallbackProps } from "@kobalte/core";
+
+<KTabs.Trigger
+	value="one"
+	as={(
+		props: PolymorphicCallbackProps<
+			MyCustomButtonProps,
+			KTabs.TabsTriggerOptions,
+			KTabs.TabsTriggerRenderProps
+		>,
+	) => (
+		// The `value` prop is directly passed to MyCustomButton
+		<MyCustomButton value="custom" {...props} />
+	)}
+>
+	Custom Button Trigger
+</KTabs.Trigger>;
+```
+
+## Event lifecycle
+
+Setting custom event handlers on component will call your custom handler before Kobalte's.
+
+## Types
+
+This section is mainly for library author that want to build on top of Kobalte and expose the correct types
+to your end users.
+
+Every component that renders an HTML element has the following types:
+
+- `ComponentOptions`
+- `ComponentCommonProps`
+- `ComponentRenderProps`
+- `ComponentProps`
+
+For example, `Tabs.Trigger` has the types `TabsTriggerOptions`, `TabsTriggerCommonProps`,
+`TabsTriggerRenderProps` and `TabsTriggerProps` namespaced as `Tabs.TabsTriggerOptions`, etc.
+
+Components themselves accept props as `PolymorphicProps<T, ComponentProps>` where `T` is a generic
+that extends `ValidComponent` and the `ComponentProps` of the Kobalte component.
+This type allows components to accept Kobalte's props and all other props accepted by `T`.
+
+### `ComponentOptions`
+
+This type contains all custom props consumed by Kobalte, these props do not exist in HTML.
+These are not passed to the HTML element nor to the `as` callback.
+
+### `ComponentCommonProps`
+
+This type contains HTML attributes optionally accepted by the Kobalte component and will
+be forwarded to the rendered DOM node. These are managed by Kobalte but can be customized by the end
+user. It includes attributes such as `id`, `ref`, event handlers, etc.
+
+### `ComponentRenderProps`
+
+This type extends `ComponentCommonProps` and additionally contains attributes that are passed
+to the DOM node and fully managed by Kobalte. You should never assign these yourself or set them on
+the Kobalte component. Modifying these props will break your component's behavior and accessibity.
+
+### `ComponentProps`
+
+This is the final type exported by components, it is equal to `ComponentOptions & Partial<ComponentCommonProps>`.
+It combines all props expected by Kobalte's component.
+
+### `PolymorphicProps<T, ComponentProps>`
+
+If you're writing a custom component and want to expose Kobalte's `as` prop to the end user
+and keep proper typing, be sure to use `PolymorphicProps<T, ComponentProps>` for your props type.
+
+```tsx
+import { Tabs as KTabs, PolymorphicProps } from "@kobalte/core";
+
+// Optionally extend `KTabs.TabsTriggerProps` if you wish to
+// expose Kobalte props to your end user.
+interface CustomProps extends KTabs.TabsTriggerProps {
+	variant: "default" | "outline";
+}
+
+// Your generic `T` should extend ValidComponent and have a default value of the default DOM node.
+function CustomTabsTrigger<T extends ValidComponent = "button">(
+	props: PolymorphicProps<T, CustomProps>,
+) {
+	// Typescript degrades typechecking when using generics, as long as we
+	// spread `others` to our element, we can effectively ignore them.
+	const [local, others] = splitProps(props as CustomProps, ["variant"]);
+
+	return (
+		<KTabs.Trigger
+			// Optional, will default to Kobalte otherwise.
+			// This should match with your generic `T` default.
+			as="button"
+			class={local.variant === "default" ? "default-trigger" : "outline-trigger"}
+			// Make sure to spread these props!
+			{...others}
+		/>
+	);
+}
+```
+
+If you also want to export exact types, you can re-export and extends component types:
+
+```tsx
+export interface CustomTabsTriggerOptions extends KTabs.TabsTriggerOptions {
+	variant: "default" | "outline";
+}
+
+export interface CustomTabsTriggerCommonProps extends KTabs.TabsTriggerCommonProps {
+	// If you allow users to set classes and extend them.
+	//class: string;
+}
+
+export interface CustomTabsTriggerRenderProps
+	extends CustomTabsTriggerCommonProps,
+		KTabs.TabsTriggerRenderProps {
+	// If you do not allow users to set classes and manage all of them.
+	class: string;
+}
+
+export type CustomTabsTriggerProps = CustomTabsTriggerOptions &
+	Partial<CustomTabsTriggerCommonProps>;
+
+export function CustomTabsTrigger<T extends ValidComponent = "button">(
+	props: PolymorphicProps<T, CustomTabsTriggerProps>,
+) {}
+```

package.json

@@ -64,7 +64,8 @@
 		"typescript": "4.9.5",
 		"vite": "5.0.11",
 		"vite-plugin-solid": "2.9.1",
-		"vitest": "1.3.1"
+		"vitest": "1.3.1",
+		"@vitest/ui": "^1.5.2"
 	},
 	"packageManager": "[email protected]"
 }