@itwin/itwinui-react 5.0.0-alpha.0 → 5.0.0-alpha.1

package/dist/bricks/ListItem.js

@@ -1,30 +1,30 @@
 import { jsx } from "react/jsx-runtime";
-import * as React from "react";
 import cx from "classnames";
 import * as Ariakit from "@ariakit/react";
-const ListItem = React.forwardRef(
+import { forwardRef } from "./~utils.js";
+const ListItem = forwardRef((props, forwardedRef) => {
+  return /* @__PURE__ */ jsx(
+    Ariakit.Role.div,
+    {
+      role: "listitem",
+      ...props,
+      className: cx("\u{1F95D}-list-item", props.className),
+      ref: forwardedRef
+    }
+  );
+});
+const ListItemContent = forwardRef(
   (props, forwardedRef) => {
     return /* @__PURE__ */ jsx(
-      Ariakit.Role.div,
+      Ariakit.Role.span,
       {
-        role: "listitem",
         ...props,
-        className: cx("\u{1F95D}-list-item", props.className),
+        className: cx("\u{1F95D}-list-item-content", props.className),
         ref: forwardedRef
       }
     );
   }
 );
-const ListItemContent = React.forwardRef((props, forwardedRef) => {
-  return /* @__PURE__ */ jsx(
-    Ariakit.Role.span,
-    {
-      ...props,
-      className: cx("\u{1F95D}-list-item-content", props.className),
-      ref: forwardedRef
-    }
-  );
-});
 export {
   ListItemContent as Content,
   ListItem as Root

package/dist/bricks/Radio.d.ts

@@ -1,9 +1,23 @@
-import * as React from "react";
 import * as Ariakit from "@ariakit/react";
-import type { FocusableProps } from "./~utils.js";
+import { type FocusableProps } from "./~utils.js";
 type InputBaseProps = Omit<FocusableProps<"input">, "defaultValue" | "value">;
 type RadioOwnProps = Pick<Ariakit.RadioProps, "value" | "checked" | "onChange">;
 interface RadioProps extends InputBaseProps, RadioOwnProps {
 }
-export declare const Radio: React.ForwardRefExoticComponent<RadioProps & React.RefAttributes<HTMLInputElement>>;
+/**
+ * A styled radio input element, typically used for selecting a single option from a list.
+ *
+ * Works well with the `Field` and `Label` components.
+ *
+ * ```tsx
+ * <Field>
+ *   <Label>Choose one</Label>
+ *   <Radio />
+ * </Field>
+ * ```
+ *
+ * Underneath, it's an HTML radio input, i.e. `<input type="radio">`, so it supports the same props,
+ * including `value`, `defaultChecked`, `checked`, and `onChange`.
+ */
+export declare const Radio: import("react").ForwardRefExoticComponent<RadioProps & import("react").RefAttributes<HTMLElement | HTMLInputElement>>;
 export {};

package/dist/bricks/Radio.js

@@ -1,9 +1,9 @@
 import { jsx } from "react/jsx-runtime";
-import * as React from "react";
 import cx from "classnames";
 import * as Ariakit from "@ariakit/react";
 import { useFieldId } from "./Field.js";
-const Radio = React.forwardRef((props, forwardedRef) => {
+import { forwardRef } from "./~utils.js";
+const Radio = forwardRef((props, forwardedRef) => {
   const fieldId = useFieldId();
   return /* @__PURE__ */ jsx(
     Ariakit.Radio,

package/dist/bricks/Root.d.ts

@@ -19,8 +19,17 @@ interface RootProps extends BaseProps {
     density: "dense";
 }
 /**
- * Component to be used at the root of your application. It ensures that kiwi styles are loaded
+ * Component to be used at the root of your application. It ensures that kiwi styles and fonts are loaded
  * and automatically applied to the current page or the encompassing shadow-root.
+ *
+ * Make sure to specify the `colorScheme` and `density` props.
+ *
+ * Example:
+ * ```tsx
+ * <Root colorScheme="dark" density="dense">
+ *   <App />
+ * </Root>
+ * ```
  */
-export declare const Root: React.ForwardRefExoticComponent<RootProps & React.RefAttributes<HTMLDivElement>>;
+export declare const Root: React.ForwardRefExoticComponent<RootProps & React.RefAttributes<HTMLElement | HTMLDivElement>>;
 export {};

package/dist/bricks/Root.js

@@ -4,47 +4,45 @@ import * as Ariakit from "@ariakit/react";
 import cx from "classnames";
 import foundationsCss from "../foundations/styles.css.js";
 import bricksCss from "./styles.css.js";
-import { isBrowser } from "./~utils.js";
+import { forwardRef, isBrowser } from "./~utils.js";
 import { useMergedRefs } from "./~hooks.js";
 const css = foundationsCss + bricksCss;
-const Root = React.forwardRef(
-  (props, forwardedRef) => {
-    const { children, synchronizeColorScheme = false, ...rest } = props;
-    return /* @__PURE__ */ jsxs(RootInternal, { ...rest, ref: forwardedRef, children: [
-      /* @__PURE__ */ jsx(Styles, {}),
-      /* @__PURE__ */ jsx(Fonts, {}),
-      synchronizeColorScheme ? /* @__PURE__ */ jsx(SynchronizeColorScheme, { colorScheme: props.colorScheme }) : null,
-      children
-    ] });
-  }
-);
+const Root = forwardRef((props, forwardedRef) => {
+  const { children, synchronizeColorScheme = false, ...rest } = props;
+  return /* @__PURE__ */ jsxs(RootInternal, { ...rest, ref: forwardedRef, children: [
+    /* @__PURE__ */ jsx(Styles, {}),
+    /* @__PURE__ */ jsx(Fonts, {}),
+    synchronizeColorScheme ? /* @__PURE__ */ jsx(SynchronizeColorScheme, { colorScheme: props.colorScheme }) : null,
+    children
+  ] });
+});
 const RootNodeContext = React.createContext(null);
 function useRootNode() {
   return React.useContext(RootNodeContext);
 }
-const RootInternal = React.forwardRef((props, forwardedRef) => {
-  const { children, colorScheme, density, ...rest } = props;
-  const [rootNode, setRootNode] = React.useState(
-    null
-  );
-  const findRootNodeFromRef = React.useCallback((element) => {
-    if (!element) return;
-    const rootNode2 = element.getRootNode();
-    if (!isDocument(rootNode2) && !isShadow(rootNode2)) return;
-    setRootNode(rootNode2);
-  }, []);
-  return /* @__PURE__ */ jsx(
-    Ariakit.Role,
-    {
-      ...rest,
-      className: cx("\u{1F95D}-root", props.className),
-      "data-kiwi-theme": colorScheme,
-      "data-kiwi-density": density,
-      ref: useMergedRefs(forwardedRef, findRootNodeFromRef),
-      children: /* @__PURE__ */ jsx(RootNodeContext.Provider, { value: rootNode, children })
-    }
-  );
-});
+const RootInternal = forwardRef(
+  (props, forwardedRef) => {
+    const { children, colorScheme, density, ...rest } = props;
+    const [rootNode, setRootNode] = React.useState(null);
+    const findRootNodeFromRef = React.useCallback((element) => {
+      if (!element) return;
+      const rootNode2 = element.getRootNode();
+      if (!isDocument(rootNode2) && !isShadow(rootNode2)) return;
+      setRootNode(rootNode2);
+    }, []);
+    return /* @__PURE__ */ jsx(
+      Ariakit.Role,
+      {
+        ...rest,
+        className: cx("\u{1F95D}-root", props.className),
+        "data-kiwi-theme": colorScheme,
+        "data-kiwi-density": density,
+        ref: useMergedRefs(forwardedRef, findRootNodeFromRef),
+        children: /* @__PURE__ */ jsx(RootNodeContext.Provider, { value: rootNode, children })
+      }
+    );
+  }
+);
 function SynchronizeColorScheme({
   colorScheme
 }) {
@@ -104,8 +102,8 @@ function Fonts() {
   return null;
 }
 function loadFonts(rootNode) {
-  const ownerDocument = getOwnerDocument(rootNode);
-  if (!ownerDocument || Array.from(ownerDocument.fonts).some(
+  const ownerWindow = getWindow(rootNode);
+  if (!ownerWindow || Array.from(ownerWindow.document.fonts).some(
     (font) => font.family === "InterVariable"
   )) {
     return;
@@ -115,12 +113,16 @@ function loadFonts(rootNode) {
     italic: "https://rsms.me/inter/font-files/InterVariable-Italic.woff2?v=4.1"
   };
   for (const [style, url] of Object.entries(interStyles)) {
-    const font = new FontFace("InterVariable", `url(${url}) format("woff2")`, {
-      display: "swap",
-      weight: "100 900",
-      style
-    });
-    ownerDocument.fonts.add(font);
+    const font = new ownerWindow.FontFace(
+      "InterVariable",
+      `url(${url}) format("woff2")`,
+      {
+        display: "swap",
+        weight: "100 900",
+        style
+      }
+    );
+    ownerWindow.document.fonts.add(font);
   }
 }
 const supportsAdoptedStylesheets = isBrowser && "adoptedStyleSheets" in Document.prototype;

package/dist/bricks/Select.d.ts

@@ -0,0 +1,45 @@
+import * as React from "react";
+import * as Ariakit from "@ariakit/react";
+import { type FocusableProps } from "./~utils.js";
+/**
+ * Compound component for a select element, which allows the user to select a value from a list of options.
+ *
+ * Works well with the `Field` and `Label` components.
+ *
+ * Example usage:
+ * ```tsx
+ * <Field>
+ *   <Label>Select an option</Label>
+ *   <Select.Root>
+ *     <Select.HtmlSelect>
+ *       <option value="1">Option 1</option>
+ *       <option value="2">Option 2</option>
+ *       <option value="3">Option 3</option>
+ *     </Select.HtmlSelect>
+ *   </Select.Root>
+ * </Field>
+ * ```
+ */
+declare const SelectRoot: React.ForwardRefExoticComponent<Pick<Ariakit.RoleProps, "render"> & Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "render"> & React.RefAttributes<HTMLElement | HTMLDivElement>>;
+interface HtmlSelectProps extends Omit<FocusableProps<"select">, "multiple" | "size"> {
+}
+/**
+ * The actual select element to be used inside `Select.Root`. This is a wrapper around the
+ * HTML `<select>` element and should render HTML `<option>` elements as children.
+ *
+ * Example usage:
+ * ```tsx
+ * <Select.HtmlSelect>
+ *   <option value="1">Option 1</option>
+ *   <option value="2">Option 2</option>
+ *   <option value="3">Option 3</option>
+ * </Select.HtmlSelect>
+ * ```
+ *
+ * The usage of this component largely mirrors how the `<select>` element would be used in React.
+ * You can use the same familiar props, including `name`, `defaultValue`, `value`, `onChange`, etc.
+ *
+ * @see https://react.dev/reference/react-dom/components/select
+ */
+declare const HtmlSelect: React.ForwardRefExoticComponent<HtmlSelectProps & React.RefAttributes<HTMLElement | HTMLSelectElement>>;
+export { SelectRoot as Root, HtmlSelect };

package/dist/bricks/Select.js

@@ -0,0 +1,55 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import cx from "classnames";
+import * as Ariakit from "@ariakit/react";
+import {
+  forwardRef,
+  isBrowser
+} from "./~utils.js";
+import { DisclosureArrow } from "./Icon.js";
+import { useFieldId } from "./Field.js";
+const supportsHas = isBrowser && CSS?.supports?.("selector(:has(+ *))");
+const HtmlSelectContext = React.createContext(() => {
+});
+const SelectRoot = forwardRef((props, forwardedRef) => {
+  const [isHtmlSelect, setIsHtmlSelect] = React.useState(false);
+  return /* @__PURE__ */ jsx(HtmlSelectContext.Provider, { value: setIsHtmlSelect, children: /* @__PURE__ */ jsx(
+    Ariakit.Role.div,
+    {
+      ...props,
+      className: cx("\u{1F95D}-select-root", props.className),
+      "data-kiwi-has-select": !supportsHas && isHtmlSelect ? "true" : void 0,
+      ref: forwardedRef
+    }
+  ) });
+});
+const HtmlSelect = forwardRef(
+  (props, forwardedRef) => {
+    const setIsHtmlSelect = React.useContext(HtmlSelectContext);
+    const fieldId = useFieldId();
+    React.useEffect(
+      function updateContext() {
+        setIsHtmlSelect(true);
+      },
+      [setIsHtmlSelect]
+    );
+    return /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(
+        Ariakit.Role.select,
+        {
+          id: fieldId,
+          ...props,
+          className: cx("\u{1F95D}-button", "\u{1F95D}-select", props.className),
+          "data-kiwi-tone": "neutral",
+          "data-kiwi-variant": "solid",
+          ref: forwardedRef
+        }
+      ),
+      /* @__PURE__ */ jsx(DisclosureArrow, { className: "\u{1F95D}-select-arrow" })
+    ] });
+  }
+);
+export {
+  HtmlSelect,
+  SelectRoot as Root
+};

package/dist/bricks/Switch.d.ts

@@ -1,6 +1,5 @@
-import * as React from "react";
 import * as Ariakit from "@ariakit/react";
-import type { FocusableProps } from "./~utils.js";
+import { type FocusableProps } from "./~utils.js";
 type InputBaseProps = Omit<FocusableProps<"input">, "defaultValue" | "value">;
 type CheckboxOwnProps = Pick<Ariakit.CheckboxProps, "value" | "defaultChecked" | "checked" | "onChange">;
 interface SwitchProps extends InputBaseProps, CheckboxOwnProps {
@@ -9,5 +8,20 @@ interface SwitchProps extends InputBaseProps, CheckboxOwnProps {
     /** The controlled checked state of the toggle switch. */
     checked?: boolean;
 }
-export declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLInputElement>>;
+/**
+ * A toggle switch element, typically used for enabling or disabling a feature.
+ *
+ * Works well with the `Field` and `Label` components.
+ *
+ * ```tsx
+ * <Field>
+ *   <Label>Enable feature</Label>
+ *   <Switch />
+ * </Field>
+ * ```
+ *
+ * Underneath, it's an HTML checkbox, i.e. `<input type="checkbox">`, so it supports the same props,
+ * including `value`, `defaultChecked`, `checked`, and `onChange`.
+ */
+export declare const Switch: import("react").ForwardRefExoticComponent<SwitchProps & import("react").RefAttributes<HTMLElement | HTMLInputElement>>;
 export {};

package/dist/bricks/Switch.js

@@ -1,22 +1,24 @@
 import { jsx } from "react/jsx-runtime";
-import * as React from "react";
 import cx from "classnames";
 import * as Ariakit from "@ariakit/react";
 import { useFieldId } from "./Field.js";
-const Switch = React.forwardRef((props, forwardedRef) => {
-  const fieldId = useFieldId();
-  return /* @__PURE__ */ jsx(
-    Ariakit.Checkbox,
-    {
-      accessibleWhenDisabled: true,
-      id: fieldId,
-      ...props,
-      className: cx("\u{1F95D}-switch", props.className),
-      role: "switch",
-      ref: forwardedRef
-    }
-  );
-});
+import { forwardRef } from "./~utils.js";
+const Switch = forwardRef(
+  (props, forwardedRef) => {
+    const fieldId = useFieldId();
+    return /* @__PURE__ */ jsx(
+      Ariakit.Checkbox,
+      {
+        accessibleWhenDisabled: true,
+        id: fieldId,
+        ...props,
+        className: cx("\u{1F95D}-switch", props.className),
+        role: "switch",
+        ref: forwardedRef
+      }
+    );
+  }
+);
 export {
   Switch
 };

package/dist/bricks/Tabs.d.ts

@@ -1,8 +1,36 @@
 import * as React from "react";
 import * as Ariakit from "@ariakit/react";
-import type { FocusableProps, BaseProps } from "./~utils.js";
+import { type FocusableProps, type BaseProps } from "./~utils.js";
 interface TabsProps extends Pick<Ariakit.TabProviderProps, "defaultSelectedId" | "selectedId" | "setSelectedId" | "selectOnMove" | "children"> {
 }
+/**
+ * A set of tabs that can be used to switch between different views.
+ *
+ * `Tabs` is a compound component with subcomponents exposed for different parts.
+ *
+ * Example:
+ * ```tsx
+ * <Tabs.Root>
+ *   <Tabs.TabList>
+ *     <Tabs.Tab id="tab-1">Tab 1</Tabs.Tab>
+ *     <Tabs.Tab id="tab-2">Tab 2</Tabs.Tab>
+ *     <Tabs.Tab id="tab-3">Tab 3</Tabs.Tab>
+ *   </Tabs.TabList>
+ *
+ *   <Tabs.TabPanel tabId="tab-1">Tab 1 content</Tabs.TabPanel>
+ *   <Tabs.TabPanel tabId="tab-2">Tab 2 content</Tabs.TabPanel>
+ *   <Tabs.TabPanel tabId="tab-3">Tab 3 content</Tabs.TabPanel>
+ * </Tabs.Root>
+ * ```
+ *
+ * The tabs and their panels are connected by matching the `id` prop on the `Tabs.Tab` component with
+ * the `tabId` prop on the `Tabs.TabPanel` component.
+ *
+ * The `Tabs` component automatically manages the selected tab state. The initially selected tab can be set using `defaultSelectedId`.
+ * To take full control the selected tab state, use the `selectedId` and `setSelectedId` props together.
+ *
+ * **Note**: `Tabs` should _not_ be used for navigation; it is only intended for switching smaller views within an existing page.
+ */
 declare function Tabs(props: TabsProps): import("react/jsx-runtime").JSX.Element;
 declare namespace Tabs {
     var displayName: string;
@@ -11,11 +39,44 @@ interface TabListProps extends BaseProps {
     /** @default "neutral" */
     tone?: "neutral" | "accent";
 }
-declare const TabList: React.ForwardRefExoticComponent<TabListProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * A simple container for the tab buttons.
+ * Should be used as a child of `Tabs.Root` and consist of the individual `Tabs.Tab` components.
+ *
+ * Example:
+ * ```tsx
+ * <Tabs.TabList>
+ *   <Tabs.Tab id="tab-1">Tab 1</Tabs.Tab>
+ *   <Tabs.Tab id="tab-2">Tab 2</Tabs.Tab>
+ *   <Tabs.Tab id="tab-3">Tab 3</Tabs.Tab>
+ * </Tabs.TabList>
+ * ```
+ */
+declare const TabList: React.ForwardRefExoticComponent<TabListProps & React.RefAttributes<HTMLElement | HTMLDivElement>>;
 interface TabProps extends FocusableProps<"button">, Pick<Ariakit.TabProps, "id"> {
 }
-declare const Tab: React.ForwardRefExoticComponent<TabProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * An individual tab button that switches the selected tab panel when clicked.
+ *
+ * Should be used as a child of `Tabs.TabList` and be paired with a `Tabs.TabPanel`,
+ * connected using an id.
+ *
+ * Example:
+ * ```tsx
+ * <Tabs.Tab id="tab-1">Tab 1</Tabs.Tab>
+ * ```
+ */
+declare const Tab: React.ForwardRefExoticComponent<TabProps & React.RefAttributes<HTMLElement | HTMLButtonElement>>;
 interface TabPanelProps extends BaseProps<"div">, Pick<Ariakit.TabPanelProps, "tabId" | "unmountOnHide"> {
 }
-declare const TabPanel: React.ForwardRefExoticComponent<TabPanelProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * The actual content of a tab, shown when the tab is selected. Should be used as a child of `Tabs.Root`.
+ * The `tabId` prop should match the `id` prop of the corresponding `Tabs.Tab` component.
+ *
+ * Example:
+ * ```tsx
+ * <Tabs.TabPanel tabId="tab-1">Tab 1 content</Tabs.TabPanel>
+ * ```
+ */
+declare const TabPanel: React.ForwardRefExoticComponent<TabPanelProps & React.RefAttributes<HTMLElement | HTMLDivElement>>;
 export { Tabs as Root, TabList, Tab, TabPanel };

package/dist/bricks/Tabs.js

@@ -4,6 +4,7 @@ import * as ReactDOM from "react-dom";
 import cx from "classnames";
 import * as Ariakit from "@ariakit/react";
 import { useControlledState } from "./~hooks.js";
+import { forwardRef } from "./~utils.js";
 function Tabs(props) {
   const {
     defaultSelectedId,
@@ -40,7 +41,7 @@ function Tabs(props) {
     }
   );
 }
-const TabList = React.forwardRef((props, forwardedRef) => {
+const TabList = forwardRef((props, forwardedRef) => {
   const { tone = "neutral", ...rest } = props;
   const viewTransitionName = `\u{1F95D}active-stripe-${React.useId().replaceAll(":", "_")}`;
   return /* @__PURE__ */ jsx(
@@ -57,20 +58,18 @@ const TabList = React.forwardRef((props, forwardedRef) => {
     }
   );
 });
-const Tab = React.forwardRef(
-  (props, forwardedRef) => {
-    return /* @__PURE__ */ jsx(
-      Ariakit.Tab,
-      {
-        accessibleWhenDisabled: true,
-        ...props,
-        className: cx("\u{1F95D}-tab", props.className),
-        ref: forwardedRef
-      }
-    );
-  }
-);
-const TabPanel = React.forwardRef((props, forwardedRef) => {
+const Tab = forwardRef((props, forwardedRef) => {
+  return /* @__PURE__ */ jsx(
+    Ariakit.Tab,
+    {
+      accessibleWhenDisabled: true,
+      ...props,
+      className: cx("\u{1F95D}-tab", props.className),
+      ref: forwardedRef
+    }
+  );
+});
+const TabPanel = forwardRef((props, forwardedRef) => {
   return /* @__PURE__ */ jsx(
     Ariakit.TabPanel,
     {

package/dist/bricks/Text.d.ts

@@ -0,0 +1,22 @@
+import { type BaseProps } from "./~utils.js";
+interface TextProps extends BaseProps {
+    /**
+     * The typography variant to use.
+     */
+    variant?: "display-lg" | "display-md" | "display-sm" | "headline-lg" | "headline-md" | "headline-sm" | "body-lg" | "body-md" | "body-sm" | "caption-lg" | "caption-md" | "caption-sm" | "mono-sm";
+}
+/**
+ * An element with text styles applied. Useful for paragraphs, headings, and other text content.
+ *
+ * Example usage:
+ * ```tsx
+ * <Text variant="display-sm">Hello, World!</Text>
+ * ```
+ *
+ * Use the `render` prop to change the underlying element (defaults to a `<div>`):
+ * ```tsx
+ * <Text render={<h1 />} variant="headline-lg">Hello, World!</Text>
+ * ```
+ */
+export declare const Text: import("react").ForwardRefExoticComponent<TextProps & import("react").RefAttributes<HTMLElement | HTMLDivElement>>;
+export {};

package/dist/bricks/Text.js

@@ -0,0 +1,19 @@
+import { jsx } from "react/jsx-runtime";
+import * as Ariakit from "@ariakit/react";
+import cx from "classnames";
+import { forwardRef } from "./~utils.js";
+const Text = forwardRef((props, forwardedRef) => {
+  const { variant, ...rest } = props;
+  return /* @__PURE__ */ jsx(
+    Ariakit.Role,
+    {
+      ...rest,
+      className: cx("\u{1F95D}-text", props.className),
+      "data-kiwi-text-variant": variant,
+      ref: forwardedRef
+    }
+  );
+});
+export {
+  Text
+};

package/dist/bricks/TextBox.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import { Icon } from "./Icon.js";
 import { Textarea } from "./Textarea.js";
-import type { FocusableProps, BaseProps } from "./~utils.js";
+import { type FocusableProps, type BaseProps } from "./~utils.js";
 interface BaseInputProps extends FocusableProps<"input"> {
 }
 interface TextBoxInputProps extends Omit<BaseInputProps, "children" | "type"> {
@@ -16,7 +16,7 @@ interface TextBoxInputProps extends Omit<BaseInputProps, "children" | "type"> {
     type?: Extract<BaseInputProps["type"], "text" | "email" | "password" | "search" | "tel" | "url" | "number" | "date">;
 }
 /**
- * Input component that allows users to enter text based values.
+ * An input component that allows users to enter text based values.
  *
  * Example usage:
  * ```tsx
@@ -24,26 +24,56 @@ interface TextBoxInputProps extends Omit<BaseInputProps, "children" | "type"> {
  * ```
  *
  * To add additional decorations, see `TextBox.Root` component.
+ *
+ * Works well with the `Field` and `Label` components.
+ * ```tsx
+ * <Field>
+ *   <Label>Enter your name</Label>
+ *   <TextBox.Input />
+ * </Field>
+ * ```
+ *
+ * Underneath, it's an HTML input, i.e. `<input>`, so it supports the same props, including
+ * `value`, `defaultValue`, `onChange`, and `disabled`.
+ *
+ * For a multiline text input, use the `TextBox.Textarea` component.
  */
-declare const TextBoxInput: React.ForwardRefExoticComponent<TextBoxInputProps & React.RefAttributes<HTMLInputElement>>;
+declare const TextBoxInput: React.ForwardRefExoticComponent<TextBoxInputProps & React.RefAttributes<HTMLElement | HTMLInputElement>>;
 interface TextBoxRootProps extends BaseProps {
 }
 /**
- * Root component allows adding additional decorations to text based inputs.
+ * Compound component for a text input. Allows adding additional decorations.
  *
  * Example usage to add an end icon:
  * ```tsx
  * <TextBox.Root>
- * 	<TextBox.Input defaultValue="Hello" />
- * 	<TextBox.Icon href={...} />
+ *   <TextBox.Input defaultValue="Hello" />
+ *   <TextBox.Icon href={...} />
  * </TextBox.Root>
  * ```
+ *
+ * Works well with the `Field` and `Label` components.
+ * ```tsx
+ * <Field>
+ *   <Label>Enter your name</Label>
+ *   <TextBox.Root>
+ *     <TextBox.Input />
+ *     <TextBox.Icon href={…} />
+ *   </TextBox.Root>
+ * </Field>
+ * ```
  */
-declare const TextBoxRoot: React.ForwardRefExoticComponent<TextBoxRootProps & React.RefAttributes<HTMLDivElement>>;
+declare const TextBoxRoot: React.ForwardRefExoticComponent<TextBoxRootProps & React.RefAttributes<HTMLElement | HTMLDivElement>>;
 interface TextBoxIconProps extends React.ComponentProps<typeof Icon> {
 }
-declare const TextBoxIcon: React.ForwardRefExoticComponent<Omit<TextBoxIconProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+/**
+ * A static icon decoration for the `TextBox.Root` component. Can be added before or after the `TextBox.Input`.
+ */
+declare const TextBoxIcon: React.ForwardRefExoticComponent<Omit<TextBoxIconProps, "ref"> & React.RefAttributes<HTMLElement | SVGSVGElement>>;
 interface TextBoxTextProps extends BaseProps<"span"> {
 }
-declare const TextBoxText: React.ForwardRefExoticComponent<TextBoxTextProps & React.RefAttributes<HTMLSpanElement>>;
+/**
+ * A static text decoration for the `TextBox.Root` component. Can be added before or after the `TextBox.Input`.
+ */
+declare const TextBoxText: React.ForwardRefExoticComponent<TextBoxTextProps & React.RefAttributes<HTMLElement | HTMLSpanElement>>;
 export { TextBoxRoot as Root, TextBoxInput as Input, Textarea, TextBoxIcon as Icon, TextBoxText as Text, };